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.

Column	Description
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
Enabled	This is used to enable or disable a client
GUID	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

Name	Data Type	Description
Content-Type	string	application/x-www-form-urlencoded

Body Parameters

Name	Data Type	Description
token	string	You can pass in your base64 encoded SAML token instead of your Cinchy username and password
client_id	string	Client Id value from Integrated Clients table
client_secret	string	GUID value from Integrated Clients table
username	string	Username of Cinchy user
password	string	Password for Cinchy user in plain text
grant_type	string	Set as "password" for username/password authentication. Set as "saml2" for SAML token authentication.
scope	string	Set as js_api

Responses

• 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.