authenticate

Overview

This method authenticates an API user and returns an access token. The access token must be passed in the Authorization header of every other API call.

Run this API first. No other API will run without a valid access token.

Permissions

No API permission is required to run this method. The username and password supplied must belong to a Catch-e user whose role is enabled for API access.

API access is enabled on a role when [gb_roles]api_access_flag is set to 'yes'. The 'Web Services' role is enabled to run APIs by default.

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

URL Examples

https://api.demo.catch-e.com/authenticate https://api.{{environment}}.catch-e.com/authenticate https://api.test.catch-e.com/authenticate

Input Fields (Header)

Key	Format	Notes	Mandatory
Client-Id	string	Client Id for your Catch-e system. Up to 128 characters; letters, numbers and hyphens only.	Yes
Content-Type	string	`application/x-www-form-urlencoded`	Yes

Input Fields (Form Data)

The request body is sent as form data (application/x-www-form-urlencoded), not JSON.

Key	Format	Notes	Mandatory
username	string	Catch-e username. Up to 200 characters; letters, numbers, full stops, @, spaces, underscores and hyphens.	Yes
password	string	Catch-e password. Up to 64 characters.	Yes
2fa_code	string	Catch-e two-factor authentication code. Exactly 6 digits. If a code is required and not supplied, a 409 is returned (see below).	No
token_timeout	integer	Token timeout in seconds, from 0 to 28800 (8 hours). If specified, the access token expires after this number of seconds. If not set, the authenticating user's role session timeout is used.	No

Example

POST /authenticate Client-Id: [CLIENT-ID] Content-Type: application/x-www-form-urlencoded username=api.user%40example.com&password=[PASSWORD]&token_timeout=3600

Response Details

Success

201 - Created

Key	Format	Notes
access_token	string	The token to pass in the `Authorization` header of subsequent requests.
expires_in	integer	Token expiry time in seconds.
token_type	string	Always `bearer`.

json

{  "access_token": "[ACCESS-TOKEN]",  "expires_in": 3600,  "token_type": "bearer" }

Using the access token

Pass the token in the Authorization header of every other API request, using this syntax:

Authorization: Bearer [ACCESS-TOKEN]

To get a new token before the current one expires without supplying the username and password again, use the renew API.

Error Response Details

Validation Message	Comments
401 - Unauthorized	1. You have not authenticated before running this API or 2. The token_timeout of the current session has passed. You need to authenticate again.

{  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",  "title": "Unauthorized",  "status": 401,  "detail": "Unauthorized" }

Validation Message	Comments
401 - Unauthorized	The username and/or password is not valid. Passwords are case sensitive.

{  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",  "title": "Unauthorized",  "status": 401,  "detail": "Authentication Failed - Invalid Username and/or Password. Password is case sensitive." }

Validation Message	Comments
401 - Unauthorized	The user's record is suspended, authentication will not be permitted.

{  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",  "title": "Unauthorized",  "status": 401,  "detail": "Authentication Failed - Login suspended" }

Validation Message	Comments
401 - Unauthorized	The user's record is locked, authentication will not be permitted.

{  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",  "title": "Unauthorized",  "status": 401,  "detail": "Authentication Failed - Login locked" }

Validation Message	Comments
406 - Not Acceptable	The Accept header of the request does not match a response format this API supports.

{  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",  "title": "Not Acceptable",  "status": 406,  "detail": "Not Acceptable" }

Validation Message	Comments
409 - Conflict	A two-factor authentication code must be specified. Run the request again with the 2fa_code field.

{  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",  "title": "Conflict",  "status": 409,  "detail": "Two factor authentication code must be specified" }

Validation Message	Comments
415 - Unsupported Media Type	The Content-Type of the request is not supported by this API.

{  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",  "title": "Unsupported Media Type",  "status": 415,  "detail": "Not Acceptable" }

Validation Message	Comments
422 - Unprocessable Entity	Pass a valid username.

{  "validation_messages": {  "username": {  "isEmpty": "Value is required and can't be empty"  }  },  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",  "title": "Unprocessable Entity",  "status": 422,  "detail": "Failed Validation" }

Validation Message	Comments
422 - Unprocessable Entity	Pass a valid username.

{  "validation_messages": {  "username": {  "invalidUserFormat": "Invalid username format"  }  },  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",  "title": "Unprocessable Entity",  "status": 422,  "detail": "Failed Validation" }

Validation Message	Comments
422 - Unprocessable Entity	Pass a valid password.

{  "validation_messages": {  "password": {  "isEmpty": "Value is required and can't be empty"  }  },  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",  "title": "Unprocessable Entity",  "status": 422,  "detail": "Failed Validation" }

Validation Message	Comments
422 - Unprocessable Entity	The 2fa_code must be a 6 digit code.

{  "validation_messages": {  "2fa_code": {  "invalidFormat": "2fa_code must be 6 digits"  }  },  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",  "title": "Unprocessable Entity",  "status": 422,  "detail": "Failed Validation" }

Validation Message	Comments
422 - Unprocessable Entity	The token_timeout must contain only digits. The maximum allowable timeout is 28800 seconds.

{  "validation_messages": {  "token_timeout": {  "notDigits": "The input must contain only digits"  }  },  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",  "title": "Unprocessable Entity",  "status": 422,  "detail": "Failed Validation" }

Validation Message	Comments
500 - Internal Error	An unexpected error occurred on the server.

{  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",  "title": "string",  "status": 599,  "detail": "string" }

Validation Message	Comments
default - Unexpected Error	Any other unexpected error.

{  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",  "title": "string",  "status": 599,  "detail": "string" }