API authentication

This page outlines API Authentication methods and details.

Authentication methods

The APIs in Cinchy use bearer token based authentication. This token is issued by the Cinchy SSO using the OAuth 2.0 Resource Owner Password Flow and can be retrieved for any Cinchy User Account or SSO Account. API calls made using a bearer token will run under the privileges of the authenticated user, and are driven by the configured data level access controls. You must include the token in each request in the Authorization header.

APIs that are dynamically generated through a Saved Query in Cinchy also allow for basic authentication. In this case, the URL to the saved query is different, it will be:

https://<Cinchy Web URL>/BasicAuthAPI/MyDomain/MyQuery

The Resource Owner Password Flow uses a combination of a client id, client secret, username, and password to authenticate both the calling application as well as the user. To get started with, you must register a client in Cinchy. You should use a different client id for each calling application to distinguish activity from each source.

If you are on Cinchy v5.5+, you can also use Personal Access Token based authentication. These can be used in APIs the same way bearer tokens can be. Review the documentation here for information on generating PATs.

Register a new client

Clients are managed in the Integrated Clients table within the Cinchy domain. To register a client, create a new record in this table. In a fresh install, only members of the Cinchy Administrators group will have access to perform this function.

Below is a description of the value that should be used for each column in the Integrated Clients table.


Client Id

A unique identifier for each client. The client will use this identifier when retrieving a bearer token.

Client Name

A friendly name for the client to help users maintaining this record.

Grant Type

The OAuth 2.0 flow that will be used during authentication. "Resource Owner Password" should be selected for API calls.

Permitted Login Redirect URLs

N/A for the Resource Owner Password flow - leave this blank

Permitted Logout Redirect URLs

N/A for the Resource Owner Password flow - leave this blank

Permitted Scopes

The list of permitted OAuth scopes, please check all available options.

Access Token Lifetime (seconds)

The time after with the token expires. If left blank, the default is 3600 seconds.

Show Cinchy Login Screen

N/A for the Resource Owner Password flow


This is used to enable or disable a client


This is a calculated field that will auto generate the client secret

API Method Table

POST:** Bearer Token Request**

https://<Cinchy SSO URL>/identity/connect/token

The Post Request will return an access token which can be used to access Cinchy APIs.

Header Parameters

NameData TypeDescription




Body Parameters

NameData TypeDescription



You can pass in your base64 encoded SAML token instead of your Cinchy username and password



Client Id value from Integrated Clients table



GUID value from Integrated Clients table



Username of Cinchy user



Password for Cinchy user in plain text



Set as "password" for username/password authentication. Set as "saml2" for SAML token authentication.



Set as js_api


  • 200: The request is successful

The expiration time is denoted in seconds.

// {
    "access_token": "eyUzI1NiIsImtpZCI6IkE4M0UwQTFEQTY1MzE0NkZENUQxOTFDMzRDNTQ0RDJDODYyMzMzMzkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJxRDRLSGFaVEZHX1YwWkhEVEZSTkxJWWpNemsifQ.eyJuYmYiOjE1NTQxMzE4MjAsImV4cCI6MTU1NDEzNTQyMCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgxIiwiYXVkIjpbImh0dHA6Ly9sb2NhbGhvc3Q6ODA4MS9yZXNvdXJjZXMiLCJqc19hcGkiXSwiY2xpZW50X2lkIjoiYWJjIiwic3ViIjoiMSIsImF1dGhfdGltZSI6MTU1NDEzMTgyMCwiaWRwIjoibG9jYWwiLCJwcm9maWxlIjoiQWRtaW5pc3RyYXRvciIsImVtYWlsIjoiYWRtaW5AY2luY2h5LmNvIiwicm9sZSI6IkNpbmNoeSBVc2VyIEFjY291bnQiLCJpZCI6ImFkbWluIiwic2NvcGUiOlsianNfYXBpIl0sImFtciI6WyJjdXN0b20iXX0.N7drAlvtFiQoN4njs1rd5ZnTvJ_x8ZEnUEi6G1GjR4FS5FyS4hC6xdsT-Zhn1yRJQMkI2HA7HMPWwjsfkZ0IlBwuC25ECkGhbjv7DlK6baHQIkqeB0aTB9aDZSxWfDhV66O0dhby6EIEa4YuGspyjQMsDpx_LimmE9alfsUU-608944ZZkS6lBJlJ9LFCC5hYKARQIMZavrftz0tFUBsDU0T2fHpLNGo5GGwG1f9jUZTWTu7s3C05EsgboW3scUfDzjS_Wf55ExwhopIg9SD6ktHYYNRaCPtfMhU-e43l6a2LH-XrmP7OfoxJP2bvTMcvQCQWUEizKHuxKLl-ehWBw",
    "expires_in": 3600,
    "token_type": "Bearer"
  • 400: For invalid parameters, a 400 error will be returned with the following JSON response with a description of the error.

    • Example:

      "error": "invalid_grant",
      "error_description": "Invalid username or password"

To get a bearer token from Cinchy, you can provide either:

  • Username and password (username, password), or

  • SAML token (token)

Failure to provide a valid set of one of the above won't return a token.

Last updated