Authentication and Authorization
CMap APIs are authenticated via JSON Web Tokens issued by our internal authority, requiring one of several OAuth2.0 flows to be performed in order to procure a token. All flows require a client application configured (detailed here).
CMap’s authority is hosted at: https://id.cmaphq.com which serves all APIs equally.
This article presumes familiarity with OAuth 2.0 and OpenID Connect. While implementing this yourself is possible, CMap recommends the use of a standard Client Library in your tech stack of choice - A list of which are made available here.
Many API testing tools also provide a graphical interface for OAuth2.0 to avoid the need to perform the requests manually - As an example, Postman’s is documented here.
Note that all CMap APIs enforce audience validation, ensuring tokens are non-transferable between resources. Resources share a scope of api_access which must be requested, alongside a resource parameter in the token request (and the authorization request if relevant), of the intended api resource (specified as the root URL, without a trailing slash).
Authorization Code Flow (Interactive)
The Authorization Code Flow requires a client application to prompt a user for login, receiving an Authorization Code, which can then be exchanged for a token. A request is made to the authority’s authorization_endpoint with a payload dictating the response. On a successful login by the user, the code returned must then be POSTed back to the authority’s token_endpoint. Typically, an authorization code exchange may look like this:
GET https://id.cmaphq.com/connect/authorize HTTP/1.1
| Query Parameter | Value |
|---|---|
| response_type | code |
| client_id | {YOUR_CLIENT_ID} |
| scope | openid%20api_access%20{OTHER_SPACE_DELIMITED_SCOPES} |
| redirect_uri | {YOUR_CALLBACK_URL} |
| resource | https%3A%2F%2Fapi.cmaphq.com |
| state | {OPTIONAL_STATE_PARAMETER} |
Note if you are using PKCE, you must append it like so:
| Query Parameter | Value |
|---|---|
| code_challenge | {GENERATED_SHA} |
| code_challenge_method | S256 |
302 https://{YOUR_CALLBACK_URL} HTTP/1.1
| Query Parameter | Value |
|---|---|
| code | {AUTH_CODE} |
| scope | openid%20api_access |
| state | {OPTIONAL_STATE_PARAMETER} |
| iss | https%3A%2F%2Fid.cmaphq.com |
| session_state | {OUR_REF} |
Requests to the token endpoint must be application/x-www-form-urlencoded
POST https://id.cmaphq.com/connect/token HTTP/1.1
| Form Parameter | Value |
|---|---|
| grant_type | authorization_code |
| client_id | {YOUR_CLIENT_ID} |
| client_secret | {YOUR_CLIENT_SECRET} |
| code | {AUTH_CODE} |
| redirect_uri | {YOUR_CALLBACK_URL} |
| resource | https%3A%2F%2Fapi.cmaphq.com |
Note if you have provided a proof key you must now provide the verifier:
| Form Parameter | Value |
|---|---|
| code_verifier | {UNHASHED_KEY} |
Rather than including the client_id and client_secret in the request body you may alternatively pass the client’s credentials in the Authorization header as a bearer token, base64 encoded, in the format client_id
Authorization: Basic e1lPVVJfQ0xJRU5UX0lEfTp7WU9VUl9DTElFTlRfU0VDUkVUfQ==
Client Credentials Flow (Machine-To-Machine)
The Client Credentials Flow allows a client application to access protected resources using its own identity, without a specific user login. This allows integrations which run without user interaction, such as timed services or sync tasks. This allows for a simplified flow, whereby a token can be procured with a single call to the authority’s token_endpoint.
Requests to the token endpoint must be application/x-www-form-urlencoded
POST https://id.cmaphq.com/connect/token HTTP/1.1
| Form Parameter | Value |
|---|---|
| grant_type | client_credentials |
| client_id | {YOUR_CLIENT_ID} |
| client_secret | {YOUR_CLIENT_SECRET} |
| resource | https%3A%2F%2Fapi.cmaphq.com |
| scope | api_access |
CMap provides an OpenID Connect Discovery configuration file to simplify connecting with OAuth, and verifying access and ID tokens. Many OAuth 2.0 libraries implement this standard, check the documentation of your preferred library to use it.
The configuration file is available at https://id.cmaphq.com/.well-known/openid-configuration, allowing consumers to obtain information needed to interact, including OAuth 2.0 endpoint locations referenced in this article.
