API authentication

Authentication methods

APIs in Cinchy, including those dynamically generated through a saved query, use one of the following authentication methods:

• Basic authentication
• Bearer token based authentication
• Personal access token based authentication

Basic authentication

Basic authentication uses your Cinchy credentials and can be run via web browser or API call. The account that runs the API must have execute access to the query.

Using basic authentication

To run an API using basic authentication, complete the following URL using the below table as a guide:

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

Column	Description	Example
Cinchy Web URL	The URL of your cinchy instance.	cinchy.net
MyDomain	The name of the domain where the query resides.	HR
MyQuery	The name of the query.	All Employees

Pass this URL either into a web browser or as a GET request.

Example web browser request

1. Paste the URL into your web browser: https://cinchy.net/BasicAuthAPI/HR/All Employees
2. When prompted, enter your Cinchy credentials to complete the request.

Example GET request

The below GET request uses basic auth by passing in your Cinchy credentials in the Header.

GET: https://cinchy.net/BasicAuthAPI/HR/All Employees

Header parameters

Name	Data Type	Description
Authorization	string	Basic username:password The username and password must be a base64 encoded value.

Bearer token authentication

This token is issued by Cinchy SSO using the OAuth 2.0 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 the Authorization header of each API request.

There are two types of OAuth 2.0 Flow grants available:

• Resource Owner Password: uses a combination of a client id, client secret, username, and password to authenticate both the calling application and the user.
• Implicit: the client requests and obtains tokens through a front channel like an SSO login screen.

To create a new bearer token:

1. Register a client in Cinchy, using a different client id for each calling application to distinguish activity from each source.
2. Use a POST request to retrieve the access token.

Registering a new client

note

By default, only members of the Cinchy Administrators group can register clients.

1. Navigate to the [Cinchy].[Integrated Clients] table.
2. Using the below table as a guide, add a new row for your client.

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.

Retrieving the token

The below POST request is used to retrieve an access token. Use the tables in this section as a guide for creating your 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 Implicit Flow. The base64 encoded SAML token provided by your single sign-on identity provider.
client_id	String	Mandatory. The Client ID from the [Cinchy].[Integrated Clients] table
client_secret	String	Mandatory. The GUID from the [Cinchy].[Integrated Clients] table
username	String	Mandatory when using Password Flow. The Cinchy username
password	String	Mandatory when using Password Flow. The plain text password for the 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"
}

Using a bearer token

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

Name	Data Type	Description
Authorization	string	Bearer <bearer_access_token>

Personal access token authentication

Cinchy v5.5+ supports personal access token based authentication.

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

Creating a personal access token

Instructions on creating personal access tokens can be found here.

Using a personal access token

Personal access token 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>