Authentication

Introduction

Combined Business uses Token-based authentication to secure access to API endpoints. The authentication endpoint provides a way for clients to obtain an access token that can be used to authenticate requests to other endpoints in the API. The Access Token Endpoint supports both profilename/password authentication as well as authentication using refresh tokens.

With token-based authentication, clients first authenticate with their profilename and password to obtain an access token. The access token is then used to authenticate requests to API endpoints without having to pass credentials with each request. Access tokens are set to expire after a short period of time, which helps improve security by ensuring that clients must regularly authenticate to maintain access. This documentation describes how to use the access token endpoint to generate an access token.

Terminology:

• Access Token- short-lived token that is used to authenticate requests with an endpoint.
• Refresh Token: A long-lived token that can be used to generate new access tokens.
• AbsoluteRefreshTokenLifetime: The maximum amount of time a refresh token can be used before it expires.
• SlidingRefreshTokenLifetime: The amount of time a refresh token can be used before it needs to be refreshed
• Credentials: A profilename and password combination that is used to authenticate a user.

Step-by-Step Guide:

Send a POST request to the access token endpoint: ../auth/token including the following fields in the request body:

• "profileName": The profile name of the profile requesting the access token.
• "password": The password of the profile requesting the access token.
• "refreshToken": If the user has a refresh token, they can use it instead of credentials.
• "generateRefreshToken": If true, a new refresh token will be generated with the access token.

If the credentials or refresh token are valid, the server will return an access token.

If "generateRefreshToken" is true, a refresh token will also be returned with the access token when using credentials. A refresh token will not be returned when using a refresh token to get access tokens or if this field is set to false.

The access token can now be used to authenticate requests to the server.

Note: The access token has a duration of 1 hour. If the token expires, a new token must be obtained. If a refresh token was generated with the access token, it can be used to generate a new access token without having to re-enter credentials. The "AbsoluteRefreshTokenLifetime" for a refresh token is 7 days, and the "SlidingRefreshTokenLifetime" is 3 days. To keep a refresh token valid for the entire 7 days, it must be used at least once every 3 days until the AbsoluteRefreshTokenLifetime value of 7 days is reached. After the refresh token has expired, the user will need to reauthenticate to obtain a new refresh token.

Call Using profilename/password

JSON

{

  "profileName": "profilename",
  "password": "password",
  "generateRefreshToken": true
}
        

Call Using Refresh Token

JSON

{

 
  "refreshToken": "xxxxxxxxxxxxxxxxx",
 
}