Authentication

Gamma APIs offer 1 of 2 ways to authenticate. Our older APIs use basic authentication. Newer APIs use JSON web tokens.

Some older APIs use their own style of authentication. You should refer to the individual API documentation for more details.

Basic Authentication

APIs which support basic authentication require you to send your combined API username and password as part of the Authorization header.

Your username and password should be combined with a single colon separating them. For example username:password You should then base64 the resulting string and send in the Authorization in the following format

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

JSON Web Token

APIs which support JSON web tokens (JWT) require you to first send a separate authentication request to retrieve your token. This authentication process follows the token request process as specified by the Open ID Connect specification.

POST https://api.gamma.co.uk/auth/token
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=username&password=password

This will return a JSON response containing your access token with expiry, and refresh token with expiry.

{
"access_token": "eyJraWQiOiJ2SHM3SUdGVXZrbTFnZVkwM2J5cmVGRVRURWdqQjZ6eTZ1YW5tM0tMSHFnPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJtY2Fzc2lkeSIsImdDb25zdW1lcklkIjoiMjQ5IiwiZ0FwcGxpY2F0aW9ucyI6WyJTZWN1cml0eUFQSSIsIm1vYmlsZS11c2FnZS1leHRlcm5hbCJdLCJnQ29uc3VtZXJTdGF0dXMiOiJMSVZFIiwiaXNzIjoidWF0LXAtYnBtc3dzLTAxOjUwNzAiLCJnQ29uc3VtZXJOYW1lIjoibWNhc3NpZHkiLCJnQ29uc3VtZXJSZXN0cmljdGlvbnMiOltdLCJleHAiOjE1MzI5NDk4MDMsImlhdCI6MTUzMjk0NTYwMywianRpIjoiZjAzZjI0OGYtNDc0Zi00ZmRiLWE5NDUtMGU5YTQxOGEzNDhlIn0.Xd-_SDg9pUcHOxIvYojk7TspZQH91wFfHqj-Z_BTcAtjfUUo5mtWb1iR--aM5uv0e9cHG2X2dlHarASpVPYh9KoDQv238qHtUr8NLBo3aoXkrWOrWBiAs6ZOdMEXYdOCZCYj5FIS_sGS47UQwAIKfhsVnHRIry8h3LshmV18vu8al_9f6fLaju2GwpFlzJtYrzsXm_tmwWoaQW_cftz-MVF5tYQx2P8P9wS8CJh6NlGh8pxaMVjRjcTwoLWg2opNAswOj-kSNZoStD9AqrFC5-MvOU6zUmPqLHj_wCummNEKZlefk3qdAPGWicAyHcSSzWVV27ehDOzVH8Hc_xiisg",
"expires_in": 600,
"token_type": "bearer",
"refresh_expires_in": 2592000,
"refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJtY2Fzc2lkeSIsImlzcyI6InVhdC1wLWJwbXN3cy0wMTo1MDcwIiwiZXhwIjoxNTM1NTQxMjAzLCJpYXQiOjE1MzI5NDU2MDQsImp0aSI6IjU4OTQ1YWRkLTY3NjktNGU1Ni1hNDE1LWQ2MjY2NzljMTU3MCJ9.I9fsz0sTp1TRjVyOUc_J3hCbWZcwwHLd4hSJ88loSk2y-DKbPFyh1tACIbK5Rm4nVXJwTTKsrBTXwcSHyn3OiN-nbtOpOlZjRAnfNRoSWGWKfR3Bz3eZcrz6WG1bRRs7FgEs9XVCT21vw_Y5ib3hii01JOct78Ff9y24H-F8WyLr58tcUFSjIwEFopilCtgRjCmLTgEC-QIO8uGPI0H45jHZ8u8dI4EasmV6AUDsTGlk7sgih3Bir5naieLhzdMQYhnbeSB3GpenWtR2J0cZQIdhfZkHw2L4MxytbXbi6bdlnNEHv8RnqkzKDKfKHyKmz_3z9Wv7uO2QBlPYUn-YfQ"
}

Once you have obtained your token, you can send it in the Authorization header to any API which support JWT. For example

Authorization: Bearer eyJraWQiOiJ2SHM3SUdGVXZrbTFnZVkwM2J5cmVGRVRURWdqQjZ6eTZ1YW5tM0tMSHFnPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJtY2Fzc2lkeSIsImdDb25zdW1lcklkIjoiMjQ5IiwiZ0FwcGxpY2F0aW9ucyI6WyJTZWN1cml0eUFQSSIsIm1vYmlsZS11c2FnZS1leHRlcm5hbCJdLCJnQ29uc3VtZXJTdGF0dXMiOiJMSVZFIiwiaXNzIjoidWF0LXAtYnBtc3dzLTAxOjUwNzAiLCJnQ29uc3VtZXJOYW1lIjoibWNhc3NpZHkiLCJnQ29uc3VtZXJSZXN0cmljdGlvbnMiOltdLCJleHAiOjE1MzI5NDk4MDMsImlhdCI6MTUzMjk0NTYwMywianRpIjoiZjAzZjI0OGYtNDc0Zi00ZmRiLWE5NDUtMGU5YTQxOGEzNDhlIn0.Xd-_SDg9pUcHOxIvYojk7TspZQH91wFfHqj-Z_BTcAtjfUUo5mtWb1iR--aM5uv0e9cHG2X2dlHarASpVPYh9KoDQv238qHtUr8NLBo3aoXkrWOrWBiAs6ZOdMEXYdOCZCYj5FIS_sGS47UQwAIKfhsVnHRIry8h3LshmV18vu8al_9f6fLaju2GwpFlzJtYrzsXm_tmwWoaQW_cftz-MVF5tYQx2P8P9wS8CJh6NlGh8pxaMVjRjcTwoLWg2opNAswOj-kSNZoStD9AqrFC5-MvOU6zUmPqLHj_wCummNEKZlefk3qdAPGWicAyHcSSzWVV27ehDOzVH8Hc_xiisg

Your access token will expire after 10 minutes. The expires_in gives the number of seconds before the token expires. When your token expires, you will need to obtain a new one. You can do this either by sending the same request you sent initially or by sending a refresh request using your refresh_token.

POST https://api.gamma.co.uk/auth/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJtY2Fzc2lkeSIsImlzcyI6InVhdC1wLWJwbXN3cy0wMTo1MDcwIiwiZXhwIjoxNTM1NTQxMjAzLCJpYXQiOjE1MzI5NDU2MDQsImp0aSI6IjU4OTQ1YWRkLTY3NjktNGU1Ni1hNDE1LWQ2MjY2NzljMTU3MCJ9.I9fsz0sTp1TRjVyOUc_J3hCbWZcwwHLd4hSJ88loSk2y-DKbPFyh1tACIbK5Rm4nVXJwTTKsrBTXwcSHyn3OiN-nbtOpOlZjRAnfNRoSWGWKfR3Bz3eZcrz6WG1bRRs7FgEs9XVCT21vw_Y5ib3hii01JOct78Ff9y24H-F8WyLr58tcUFSjIwEFopilCtgRjCmLTgEC-QIO8uGPI0H45jHZ8u8dI4EasmV6AUDsTGlk7sgih3Bir5naieLhzdMQYhnbeSB3GpenWtR2J0cZQIdhfZkHw2L4MxytbXbi6bdlnNEHv8RnqkzKDKfKHyKmz_3z9Wv7uO2QBlPYUn-YfQ

A refresh token lasts for 30 days. The refresh_expires_in gives the number of seconds before the refresh token expires. When you send a refresh request, you will receive the same JSON response as you did previously, containing a new token and a new refresh token. A refresh token may be used only once.

Note For obtaining JSON web tokens against APIs in the Test/QA environment, the https://api-test.gamma.co.uk/auth/token URL should be use to obtain and refresh tokens

Handling Errors

400Indicates that one or more of the parameters were not valid or were missing.

401Applies to a username and password request. Indicates the supplied username and/or password was not correct.

Testing

Many Gamma APIs are offered with a separate test instance. If you're using a test version of an API you can request your JWT from https://api-test.gamma.co.uk/auth/token