Generate an access token to be included in the header of all other API calls.

Authorization (OAuth)

Arity’s APIs use the OAuth 2.0 authorization framework; each request from a client must include a valid access token in the Authorization header parameter.

Because the client is also the resource owner in all cases, Arity supports the client credentials authorization flow and does not require any involvement from end-users. A client sends a request containing its client ID and client secret, and Arity returns an access token used to authorize subsequent requests.

Request an access token

Use the generateAccessToken operation to generate a token.

Note: Arity’s Roadside Services product currently uses a separate OAuth operation, which you can find here.

The body of the request will include the following parameters:

Parameter	Required or optional	Description
client_id	Required	The client ID for your approved app, which can be found in the Dashboard
client_secret	Required	The client secret for your approved app, which can be found in the Dashboard
grant_type	Required	Value must be client_credentials
scope	Required	Value can be b2b or mobile (explained in “Scopes” section below)
userId	Optional (only used when scope=mobile)	Associates an end-user to a mobile-scope access token
deviceId	Optional (only used when scope=mobile)	Associates an end-user’s device to a mobile-scope access token

Scopes

The scope of an access token determines its permissions (i.e., which endpoints it authorizes). There are two scope values to give you and your end-users different permissions:

b2b: Enables partner developers to interact with the Arity platform. This scope authorizes all endpoints except trip upload, which must come from the end-user. Tokens with this scope expire every hour (3600 seconds).
mobile: Limited scope that enables end-users to interact with the Arity platform. These tokens are associated with a registered user when they are generated, and must be stored on that user’s device at the app layer. Tokens with this scope never expire.

Sample request

POST /platform/oauth/v1/token HTTP/1.1
Host: api-staging.arity.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded

client_id=2ZLqffbR2cBgZkPKJzMNwbvjKRAZq5aa&client_secret=NgMhygxCSAtV9PxG&grant_type=client_credentials&scope=b2b&userId=&deviceId=

Arity returns a token

Along with the access token, Arity returns three other values in the JSON response:

token_type: Will always be bearer
expires_in: Seconds until the token expires (3599 when scope=b2b, 0 when scope=mobile meaning token never expires)
scope: Will match the scope value sent in the request

Sample response

{
  "access_token": "OwF1HUTwI8L3AWUD6GiEA7AjhIK9",
  "token_type": "BearerToken",
  "expires_in": "3599",
  "scope": "b2b"
}

Note: These parameters are returned regardless of scope (userId and deviceId are not returned when scope=mobile).

Include valid token in subsequent requests

After you receive a valid access token, you must include it in the Authorization header parameter of all other requests. The token must always be preceded by the word Bearer and a space. For example, the request to view trip details should look like this:

GET /drivingBehavior/v2/trips/{{tripid}} HTTP/1.1
Host: api-staging.arity.com
Accept: application/json
Authorization: Bearer OwF1HUTwI8L3AWUD6GiEA7AjhIK9