Session Management

In order to integrate with Copilot, you would need to create a short-term access token by using the API POST /v2/api/management/copilot_connect/auth/token, authenticated with your CLIENT_ID and CLIENT_SECRET in a Basic Authentication.

💡 CLIENT_ID and CLIENT SECRET credentials should be saved and secured properly in order to preverntprevent data theft.

Create Authentication header

How to build the header

The Authentication header is built from an 'authentication scheme' part and a 'credentials' part, separated by a space.

The authentication scheme should be Basic, and the credentials part should be built by concatenating the CLIENT_ID value, a single colon character (":"), and the CLIENT_SECRET value, encoded to base64.

💡 You can create the Authentication token on bash shell by using the following command:
echo Basic $(echo -n <CLIENT_ID>:<CLIENT_SECRET> | base64) Alternatively, use the basic Authentication option in your http client.

Example

In case of the following credentials:

  • CLIENT_ID : ABABABABQQIRZ
  • CLIENT_SECRET : k9H2Nd3T5j5EW2Fu160l11Hal3x3oa

The credentials part will be:

QUJBQkFCQUJRUUlSWjprOUgyTmQzVDVqNUVXMkZ1MTYwbDExSGFsM3gzb2E=

The Authorization header will be:

Basic QUJBQkFCQUJRUUlSWjprOUgyTmQzVDVqNUVXMkZ1MTYwbDExSGFsM3gzb2E=

Creating the session

The following command will return the short-term access token.

Url

POST https://<YOUR_BASE_URL>/v2/api/management/copilot_connect/auth/token

Headers

Authorization: Basic <YOUR_CREDENTIALS_PART>
Content-Type: application/json

Replace <YOUR_CREDENTIALS_PART> with the base64 string as described above.

Body

This body should be fixed (grant_type value should not be changed)

{
  "grant_type": "client_credentials"
}

Response

Success

{
    "access_token":"<ACCESS_TOKEN>",
    "token_type":"Bearer",
    "expires_in":600
}
Response Model - AccessTokenResponse
  • access_token - The access token issued by Copilot.cx Authorization server
  • token_type - The type of the token that was issued
  • expires_in - Lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated.

(based on the OAuth2.0 RFC Section 4.2.2)

Failures

When the basic authorization token is invalid or not provided:

HTTP: HTTP/1.1 401 Unauthorized

{
  "error":"invalid_client",
  "error_description":"Client authentication failed"
}

When the request is invalid, e.g grant_type was not provided or not equal to client_credentials:

HTTP : HTTP/1.1 400 Bad Request

{
  "error": "unsupported_grant_type",
  "error_description": "grant_type must be client_credentials"
}

Example

For example:

Your BASE_URL is:

https://api.this-is-an-example-environment.bycopilot.com

Your credentials are:

  • CLIENT ID : ABABABABQQIRZ
  • CLIENT SECRET : k9H2Nd3T5j5EW2Fu160l11Hal3x3oa

You type the following command on bash shell:

echo Basic $(echo -n ABABABABQQIRZ:k9H2Nd3T5j5EW2Fu160l11Hal3x3oa | base64)

And get the token:

Basic QUJBQkFCQUJRUUlSWjprOUgyTmQzVDVqNUVXMkZ1MTYwbDExSGFsM3gzb2E=

The API request will be:

curl -X POST \
'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/auth/token' \
-d "{\"grant_type\": \"client_credentials\"}" \
-H 'Authorization: Basic QUJBQkFCQUJRUUlSWjprOUgyTmQzVDVqNUVXMkZ1MTYwbDExSGFsM3gzb2E=' \
-H 'Content-Type: application/json'

Alternatively, you can use Basic Authentication built in curl:

curl -X POST \
'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/auth/token' \
-d "{\"grant_type\": \"client_credentials\"}" \
-u ABABABABQQIRZ:k9H2Nd3T5j5EW2Fu160l11Hal3x3oa \
-H 'Content-Type: application/json'

The response will be:

{
    "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQxMjczNzUwNSwiand0VmVyc2lvbiI6Imp3dDEifQ.pF25GcYW1HNLeG1KRVPcD7Zys8MSTdTKBCURS5DF984",
    "token_type":"Bearer",
    "expires_in":600
}

Authenticate a request

Every request should include Authorization header with the <token_type> <access_token>. In the example above, all the calls should include the following header:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQxMjczNzUwNSwiand0VmVyc2lvbiI6Imp3dDEifQ.pF25GcYW1HNLeG1KRVPcD7Zys8MSTdTKBCURS5DF984

For example you can get the users using the API call:

curl -X GET \
 'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/users' \
 -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQxMjczNzUwNSwiand0VmVyc2lvbiI6Imp3dDEifQ.pF25GcYW1HNLeG1KRVPcD7Zys8MSTdTKBCURS5DF984' \
 -H 'Content-Type: application/json'
← Hello copilotUser →