How to authenticate API calls

This section explains how to authenticate your API calls.

The following topics are covered:

  • Authentication using OAuth 2.
  • What is an access token?
  • How to get an access token.
  • How to include an access token in a call.



Authentication using OAuth 2

API calls that you make are authenticated using OAuth 2. OAuth 2 is an open standard for authorisation. It relies on the use of access tokens rather than credentials (such as a username and password). One of the benefits of OAuth 2 is that you do not need to transmit user credentials over the wire when making calls. Instead, the OAuth process provides you with an access token that you send with your API calls. The access token is used for authentication purposes.



What is an access token?

An access token is a credential that you use when making API calls. It is a unique string of numbers and letters that you include with your API calls to validate that you have permission to access the API. Your access token is private and must be kept confidential.



How to get an access token

You request an access token by making a POST request to the /authorization endpoint. In the POST request you must provide the username and password that you use to log in to the platform. The access token inherits the same permissions as your user has. This means the actions you can perform using the API are the same as those you can perform using the platform.

An example POST request looks like this:

Example Request
POST "https://api.iot-x.com/authorization?username=<Your Username>&password=<Your Password>"

The response you receive from this request is a JSON body which includes your access token.

Example Response
{
	"token_type":"access",
	"access_token":"d567fde24865df35defff57862dw2r42"
	"expires_in":"899"
}

The fields included in the response body are:

FieldDescription
token_typeThis is the type of token returned.
access_tokenThis is the token's value. You must include this value in your API calls.
expires_inThis is how long the token is available for before it expires. This value is expressed in seconds.



How to include an access token in a call

You must include your token in the call's HTTP authorization header as a bearer credential.

Example Header with an Access Token
curl https://api.iot-x.com/path/to/resource -H "Authorization: Bearer d567fde24865df35defff57862dw2r42"