API authentication

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.

Authenticate with a PAT

Personal Access Tokens are created in the Settings menu of a specific user, and all associated access controls are applied and honoured when calling the token. A single user can have up to 5 active PATs at once, and they have a maximum expiry date of 1 year.

You can find details on how to create PATs by reviewing the documentation here.

PATs can be used within APIs by prefixing the token with Bearer and passing it through the Header.

Name	Data Type	Description
Authorization	string	Bearer <personal_access_token>

OAuth (Resource Owner Password or Implicit Flows)

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	Example
Client Id	A unique identifier for each client. The client will use this identifier when retrieving a bearer token.	cinchy-client
Client Name	A friendly name for the client to help users maintaining this record.	Cinchy Client
Grant Type	The OAuth 2.0 flow that will be used during authentication when retrieving a bearer token. This will either be: - Resource Owner Password: Uses credentials baked into the access token request (Username, Password, Client ID, etc.). - Implicit: The client requests and obtains a tokens through a front channel (ex: SSO login screen).	Implicit
Permitted Login Redirect URLs	URLs that a successful login can be redirected to, separated by a semicolon. When using "Resource Owner Password" grant type, this field should be left blank.	myapp.net/app
Permitted Logout Redirect URLs	URLs that a successful logout can be redirected to, separated by a semicolon. When using the "Resource Owner Password" grant type, this field should be left blank.	myapp/net/app
Permitted Scopes	The list of permitted OAuth scopes, which define the level of access the app has to a user's account. This is a multi-select choice column that includes: - Id - Roles - OpenId - Profile - Email The client must be given either read:all or write:all access: - read:all - scope will be able to read data - write:all - scope will be able to both read and write data
Access Token Lifetime (seconds)	The time after with the token expires. If left blank, the default is 3600 seconds.	3600
Show Cinchy Login Screen	You can deselect this option to have SSO as your default authentication, thereby skipping the Cinchy login screen. Deselect this option when using the "Resource Owner Password" grant type.
Enabled	This is used to enable or disable a client	Enabled
GUID	This is a calculated field that will auto generate the client secret, which is used when creating Bearer Tokens

Bearer token request

POST: https://{Cinchy SSO URL}/identity/connect/token

This API call retrieves an access token for Cinchy APIs.

Header parameters

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

Body parameters

Name	Data Type	Description
token	string	Mandatory when using SSO Flow. Base64 encoded SAML token provided by your single sign-on identity provider.
client_id	string	Mandatory. Client ID from Integrated Clients table
client_secret	string	Mandatory. GUID from Integrated Clients table
username	string	Mandatory when using Password Flow. Cinchy username
password	string	Mandatory when using Password Flow. Plain text password for Cinchy user
grant_type	string	Mandatory. "password" for username/password auth; "saml2" for SAML token auth
scope	string	Mandatory. Cinchy v5.9 or below: set as js_api Cinchy v5.10+: This should match the "Permitted Scopes" column from the [Cinchy].[Integrated Clients] table of the associated client.

Example Request Body (Password Flow)

{
  "client_id": "mortgage-app",
  "client_secret": "463ERFBC-2C=KKF-45F0-8D92-F6912SA8F1",
  "grant_type": "password",
  "username": "admin",
  "password": "password",
  "scope": "write:all"
}

Example Request Body (SSO Flow)

{
  "client_id": "mortgage-app",
  "client_secret": "463ERFBC-2C=KKF-45F0-8D92-F6912SA8F1",
  "grant_type": "saml2",
  "token": "660797583040977822RMT2JELXTZBMEO",
  "scope": "write:all"
}

Responses

• 200: Successful request

  {
    "access_token": "eyUzI1NiIsImtpZCI6IkE4M0UwQTFEQTY1M0RDJDODYyMzMzMzkw",
    "expires_in": 3600,
    "token_type": "Bearer"
  }
• 400: Invalid parameters

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

info

• To get a bearer token, provide either username and password or a SAML token.
• Token expiration time is in seconds.