Authentication

To access Senseye's APIs a valid access token needs to be provided by the client in the Authorization header of their request. There are currently two types of access tokens that can be used:

• Machine Token - A machine token is a temporary, or long-lived, token which is only allowed to perform specific actions and is not associated with a user
• User Token - A user token is a temporary token which is associated with a particular user, with all the permissions of that user

Both types of token can be used, however it is recommended to use machine tokens for integration purposes (machine-machine interfaces) and user tokens for performing actions as, or on behalf of, a user.

Please note, each token uses a different standard for encoding information. Machine tokens use paseto v4 while user tokens use jwt.

Machine Tokens¶

Machine tokens can only be generated by Senseye support. If you require a machine token please log a support ticket in our support centre or by emailing support, noting your organization, which actions the token should permit the bearer to perform, a name for the token, and an expiry date for the token if the token should not be permanent. A table of available permissions can be found below.

You can request that a previously generated machine token be invalidated by logging a support ticket referencing the name of the token.

User Tokens¶

Senseye provides an authentication https://api.senseye.io/oauth/token to request a user token, which uses your Senseye username and password to authenticate. A user token can be requested by making a POST request to the authentication endpoint with the following details in x-www-form-urlencoded format:

• grant_type: password
• username: Your Senseye Username
• password: Your Senseye Password

Please note, as the contents are expected to be URL encoded you may need to manually encode your credentials depending on the client you are using.

POST /oauth/token HTTP/1.1
Host: api.senseye.io
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=senseye_username&password=senseye_password

curl --location --request POST 'https://api.senseye.io/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=senseye_username' \
--data-urlencode 'password=senseye_password'

This provides a JSON response containing the JSON Web Token (JWT) based access token:

{
    "access_token": "your_access_token",
    "expires_in": 86400,
    "token_type": "Bearer"
}

The expires_in key of the returned json specifies how long the provided user token is valid for in seconds.

It is strongly recommended that a user token is cached and the same token is used for requests sent during the lifetime of the token. Once a token has expired, a new user token can be requested and similarly cached. To avoid failed requests, it is recommended to request a new token (known as refreshing the token) a minute before it expires.

Please note, Senseye's authentication endpoint https://api.senseye.io/oauth/token is rate limited. If a user exceeds the rate limit a HTTP 429 (Too Many Requests) status code will be returned.

Alternatively if you are trying to request a token using a 3^rd party HTTP request client (such as Postman or Insomnia), the endpoint conforms to the Resource Owner Password Credentials OAuth 2.0 standard. This is supported directly by most HTTP request clients. You will need to provide the following parameters when authenticating:

• Token URL: https://api.senseye.io/oauth/token
• Username: Your Senseye username
• Password: Your Senseye password

Making Requests¶

Requests to Senseye's APIs should include an access token in the Authorization header prefixed with Bearer. As an example, the following requests your organization's name from our GraphQL API:

POST /v1/graphql HTTP/1.1
Host: api.senseye.io
Authorization: Bearer your_access_token
Content-Type: application/json

{"query":"{organization {name}}","variables":{}}

curl --location --request POST 'https://api.senseye.io/v1/graphql' \
--header 'Authorization: Bearer your_access_token' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"{organization{name}}","variables":{}}'