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.
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
Body Parameters
Responses
200: The request is successful
The expiration time is denoted in seconds.
400: For invalid parameters, a 400 error will be returned with the following JSON response with a description of the error.
Example:
To get a bearer token from Cinchy, you can provide either:
Username and password (
username
,password
), orSAML token (
token
)
Failure to provide a valid set of one of the above won't return a token.
Last updated