API Authorization

Getting an OAuth 2.0 access token and sending it with every API request.

Requests to the Cutwise API are authorized with an OAuth 2.0 access token. This page shows how to get the token, how to refresh it and how to send it with a request.

The Cutwise authorization server follows RFC 6749 "The OAuth 2.0 Authorization Framework".

Note

For security, Cutwise strongly recommends that you use one of the OAuth 2.0 flows over HTTPS (TLS 1.2).

Example

Send the access token in the Authorization header:

GET /v3/diamond/123 HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer YzU5NDczNTMwMDY2YWY1ZjM5YmViNGJlMTU2ZmI2YjZmNjJjYjE0Y2Y5MmVhNmEyNzIxY2IxMzk1N2EzNWYyMw

The header format is described in RFC 6750, section 2.1.

Get an access token

  • Method and path: POST https://cutwise.com/api/oauth/v2/token, password grant
  • Auth: your Cutwise login and password, plus the client application ID and secret
  • Request: query parameters, see the table below
  • Response: JSON object with the access token and the refresh token

The password grant is described in Password Grant (oauth.com) and in RFC 6749, section 1.3.3.

POST https://cutwise.com/api/oauth/v2/token?grant_type=password&username={CUTWISE_LOGIN}&password={CUTWISE_PASSWORD}&client_id={CUTWISE_CLIENT_ID}&client_secret={CUTWISE_CLIENT_SECRET}
Parameter Description
CUTWISE_LOGIN Cutwise user login. The API authenticates every request as this user.
CUTWISE_PASSWORD Cutwise user password.
CUTWISE_CLIENT_ID Client application ID.
CUTWISE_CLIENT_SECRET Client application secret.

Response:

{
  "access_token": "NDZmOTU2OGQyNDMzOTIyNDNjNDRhMWVlZWE0NmI1YzM3YTVmZmIxYzUyMmE0ODU3YjYyMmJlZWMzM2JjYjg5Zg",
  "expires_in": 604800,
  "token_type": "bearer",
  "scope": "user",
  "refresh_token": "MTJkNDAxNzcwYmQyYzQzNGFiMDczZmUxYjMyN2YzOGUzYTRkYzMyZGQ1ZWNlNmI1YTI4MjBjNTY4YjUzMmIyOA"
}
Field Description
access_token Send it in the Authorization: Bearer header of every request.
expires_in Lifetime of the access token, in seconds.
token_type Token type: bearer.
scope Scope of the token.
refresh_token Use it to get a new access token when the current one expires.

Refresh the access token

  • Method and path: POST https://cutwise.com/api/oauth/v2/token, refresh token grant
  • Auth: the refresh token, plus the client application ID and secret
  • Request: query parameters, see the table below
POST https://cutwise.com/api/oauth/v2/token?grant_type=refresh_token&refresh_token={REFRESH_TOKEN}&client_id={CUTWISE_CLIENT_ID}&client_secret={CUTWISE_CLIENT_SECRET}
Parameter Description
REFRESH_TOKEN Refresh token from the access token response or from an earlier refresh.
CUTWISE_CLIENT_ID Client application ID.
CUTWISE_CLIENT_SECRET Client application secret.

A refresh token works only once.

Errors

Status code What it means What to do
401 Unauthorized The request has no access token, or the token has too few rights. Get an access token from the Cutwise OAuth server and send it in the Authorization: Bearer header.
403 Access Denied The access token has no right to read or change the requested resource. Use a token of a user who has access to the resource.

The error body formats are on the Error handling page.

Related pages