Cobra Api

Authentication

OAuth2

The OAuth2 implementation of Cobra provides authorization flows for web applications, desktop applications, mobile devices. To authorize access to protected resources OAuth2 makes use of Grant types.

Grant types

Cobra supports the following grant types:

Grant typeDescription
Authorization Code flow Developers should implement this flow to obtain an authorization code and then exchange it for a token.
Client Credentials flow This flow is intended for server to server applications, where no user interaction is required.
The client can request an access token using only its client credentials when the client is requesting access to the protected resources.
The client credentials grant type can only be used by confidential clients.

Scopes

Scopes let you specify exactly what type of access you need. Scopes limit access for OAuth tokens. They do not grant any additional permission beyond that which the user already has.

ScopeDescriptionUsed in flow
Singlesignon Use this scope to request explicitly the SingleSignOn and the UserInfo endpoint (information about the currently logged in user in Cobra). Authorization code flow
CustomerThis scope is intended for read/write actions on all Resources.Authorization code flow, Client credentials flow

Authorization Code flow

Overview

To authenticate each request requires an access token. Tokens are unique to a user and should be stored securely. In order to receive a token, you must do the following:

  1. Direct the user to our authorization url

    If the user is not logged in, they will be asked to log in. Next the user will be asked if they'd like to give your application access to their data.

  2. Receive the redirect from Cobra

    Once a user successfully authenticates and authorizes your application, the server will redirect the user to a URI of your choice with a code parameter.

  3. Request an access token

    In the previous step, you have received a code which you’ll have to exchange in order to receive an access token for the user. To make this exchange, you have to POST this code, along with some identification parameters to our token endpoint.

  4. Authenticate using the access token

    You can now use the access token for authentication and authorization until it expires.

  5. Refresh the access token

    To refresh the access token you can simply request an new access token using the refresh token, you received together with your access token, in step three.

For easy access use a client library. To see OAuth in action go to Ipsum and try the secure example.

Scopes

The supported scopes for the OAuth Authorization Code flow:

  • Singlesignon
  • Customer

Step One: Direct the user to our authorization URL

Replace the client-id, redirect-uri and scope with your values.

https://api.ctbps.nl/v3/Identity/OAuth/Authorize?client_id=client-id&redirect_uri=redirect-uri&scope=customer&response_type=code

Note: Your redirect URI's host and path must match exactly (including trailing slashes) to your registered redirect_uri. You may include additional query parameters in the supplied redirect_uri, if you need to vary your behavior dynamically.

See the section above for the supported scopes.

At this point, we present the user with a login screen and then a confirmation screen where they approve your access to their data.

Step Two: Receive the redirect from Cobra

Once a user successfully authenticates and authorizes your application, we will redirect the user to your redirect_uri with a code parameter that you’ll use in step three.

https://your-redirect-uri?code=code

If your request for approval is denied by the user, we will redirect the user to your redirect_uri with a error parameter telling you that access has been denied

https://your-redirect-uri?error=access_denied

It is your responsibility to fail gracefully in this situation and display a corresponding error message to your user.

Step Three: Request an access token

In the previous step, you have received a code which you’ll have to exchange in order to receive an access_token for the user. To make this exchange, you have to POST this code to our token endpoint along with some parameters:

  • client_id: your client id.
  • client_secret: your client secret.
  • grant_type: authorization_code.
  • redirect_uri: the redirect_uri you used in the authorization request in step one.
  • code: the exact code you received during the authorization step.
https://api.ctbps.nl/v3/OAuth/Token

Step Four: Authenticate using the access token

In the previous step you received a neatly packaged OAuth response like this:

{
    "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N",
    "token_type":"bearer",
    "epxpires_in":3600,
    "refresh_token":"9becdb02f15c44fbbf4551db6bd27f58"
}
To authenticate use the access_token and simply include it in the Authorization HTTP header.

Note: If you used the singlesignon scope in Step 1, use the AccessToken to request information about the currently logged in user in Cobra using the UserInfo endpoint. 

authorization: Bearer access_token

Step Five: Refresh the access token

The access_token expires after 1 hour per default, but you can refresh it using the refresh_token you received. To make this exchange, you have to POST your refresh_token to our token endpoint along with some parameters:

  • client_id: your client id
  • client_secret: your client secret
  • grant_type: refresh_token
  • refresh_token: the refresh_token you received with your OAuth Token.

When you make this exchange the refresh_token expires, but you'll receive a new one together with your access_token.

Client Credentials flow

This flow is intended for server to server applications, where no user interaction is required.

The application requests an access token by sending its credentials, its client ID and client secret, to the authorization server.
The Client Secret should not be shared.

To make this exchange, you have to POST these parameters to our token endpoint:

  • scope: customer.
  • grant_type: client_credentials.
https://api.ctbps.nl/v3/OAuth/Token
To authenticate use the base64 code of the clientId and client secret and simply include it in the Authorization HTTP header. 
Authorization: "Basic [base64 code]"
To generate a base64 Code you need to encode this format: client_id:client_secret

Scopes

The supported scopes for the OAuth Client Credentials flow:

  • Customer