OAuth

📘
Enterprise Feature
This feature is only available to customers with an enterprise Platform subscription. Please get in touch to discuss enabling it on your account.

To enable OAuth 2.0, developers need to register an OAuth client Platform resource for their application. An OAuth client resource represents any web-based or native application that will interact with the platform on behalf of the Application User, using their API key.

The EVRYTHNG Platform allows registration of multiple OAuth clients for the application. The registration process requires a redirect URL where users will be directed after allowing or declining access for the application.

Each successfully registered client is granted unique credentials. As long as the platform supports only Implicit Grant authorization flow, the client ID is the only part of the credentials that is needed to obtain the Application User access token.

API Status
General Availability:
/projects/:projectId/applications/:applicationId/oauthClients
/projects/:projectId/applications/:applicationId/oauthClients/:clientId
auth.evrythng.com/oauth/authorize

Jump To ↓

OAuthClientDocument Data Model
Create an OAuth Client
Read All OAuth Clients
Read an OAuth Client
Update an OAuth Client
Delete an OAuth Client
OAuth Authorize

OAuthClientDocument Data Model

.id (string, read-only)
    The ID of the OAuth client.

.name (string)
    The name of the OAuth client.

.redirectUrl (string)
    The OAuth redirect URL. Must be a valid absolute URL under 
    HTTPS protocol.

.createdAt (integer, read-only)
    Timestamp when the resource was created.

.updatedAt (integer, read-only)
    Timestamp when the resource was updated.

.customFields (object)
    Object of case-sensititve key-value pairs of custom fields 
    associated with the resource.

{
  "type": "object",
  "description": "An object representing an OAuth client.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the OAuth client.",
      "minLength": 45,
      "maxLength": 45,
      "readOnly": true
    },
    "name": {
      "type": "string",
      "description": "The name of the OAuth client."
    },
    "redirectUrl": {
      "type": "string",
      "description": "The OAuth redirect URL. Must be a valid absolute URL under HTTPS protocol."
    },
    "createdAt": {
      "type": "integer",
      "description": "Timestamp when the resource was created.",
      "readOnly": true,
      "minimum": 0
    },
    "updatedAt": {
      "type": "integer",
      "description": "Timestamp when the resource was updated.",
      "readOnly": true,
      "minimum": 0
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    }
  }
}

{
  "id": "AViIrsX3zYYibHr4FZXAEIE0bdD1RLhff7nedB5bT8kr",
  "name": "Example Client",
  "redirectUrl": "https://examples.com/oauth/callback",
  "customFields": {
    "type": "Web Application",
    "homeUrl": "https://examples.com"
  },
  "createdAt": 1433508108657,
  "updatedAt": 1433508108657
}

Create an OAuth Client

Registers a new OAuth client granted with unique client ID.

POST /projects/:projectId/applications/:applicationId/oauthClients
Content-type: application/json
Authorization: $OPERATOR_API_KEY

OAuthClientDocument

curl -i -H "Content-type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/projects/U2meqbNWegsaQKRRaDUmpssr/applications/UF3Vqb7D6G8EhMwaRYgQ2pFc/oauthClients' \
  -d '{
    "name": "Example Client",
    "redirectUrl": "https://examples.com/oauth/callback",
    "customFields": {
      "type": "Web Application",
      "homeUrl": "https://examples.com"
    }
  }'

const projectId = 'Uh5qRBqc4DcmbNbAANtMnrYm';
const applicationId = 'Uh6GfhFnmgScpnxwMsqmbbBk';

const payload = {
  name: 'Example Client',
  redirectUrl: 'https://examples.com/oauth/callback',
  customFields: {
    type: 'Web Application',
    homeUrl: 'https://examples.com'
  }
};

evrythng.api({
  url: `/projects/${projectId}/applications/${applicationId}/oauthClients`,
  apiKey: operatorApiKey,
  method: 'post',
  data: payload,
}).then(console.log);

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "AViIrsX3zYYibHr4FZXAEIE0bdD1RLhff7nedB5bT8kr",
  "name": "Example Client",
  "redirectUrl": "https://examples.com/oauth/callback",
  "customFields": {
    "type": "Web Application",
    "homeUrl": "https://examples.com"
  },
  "createdAt": 1433508108657,
  "updatedAt": 1433508108657
}

Read All OAuth Clients

Returns an array of OAuth clients.

GET /projects/:projectId/applications/:applicationId/oauthClients
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://api.evrythng.com/projects/U2meqbNWegsaQKRRaDUmpssr/applications/UF3Vqb7D6G8EhMwaRYgQ2pFc/oauthClients'

const projectId = 'Uh5qRBqc4DcmbNbAANtMnrYm';
const applicationId = 'Uh6GfhFnmgScpnxwMsqmbbBk';

evrythng.api({
  url: `/projects/${projectId}/applications/${applicationId}/oauthClients`,
  apiKey: operatorApiKey,
}).then(console.log);

HTTP/1.1 200 OK
Content-type: application/json

[
  {
    "id": "AViIrsX3zYYibHr4FZXAEIE0bdD1RLhff7nedB5bT8kr",
    "name": "Example Client",
    "redirectUrl": "https://examples.com/oauth/callback",
    "customFields": {
      "type": "Web Application",
      "homeUrl": "https://examples.com"
    },
    "createdAt": 1433508108657,
    "updatedAt": 1433508108657
  }
]

Read an OAuth Client

Reads the OAuth client.

GET /projects/:projectId/applications/:applicationId/oauthClients/:clientId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://api.evrythng.com/projects/U2meqbNWegsaQKRRaDUmpssr/applications/UF3Vqb7D6G8EhMwaRYgQ2pFc/oauthClients/AViIrsX3zYYibHr4FZXAEIE0bdD1RLhff7nedB5bT8kr'

const projectId = 'Uh5qRBqc4DcmbNbAANtMnrYm';
const applicationId = 'Uh6GfhFnmgScpnxwMsqmbbBk';
const oauthClientId = 'AMWefPQKd1jcQzgizqY2z22x4jhDUaij8d2V72Fq7565r';

evrythng.api({
  url: `/projects/${projectId}/applications/${applicationId}/oauthClients/${oauthClientId}`,
  apiKey: operatorApiKey,
}).then(console.log);

HTTP/2.2 200 OK
Content-type: application/json

{
  "id": "AViIrsX3zYYibHr4FZXAEIE0bdD1RLhff7nedB5bT8kr",
  "name": "Example Client",
  "redirectUrl": "https://examples.com/oauth/callback",
  "customFields": {
    "type": "Web Application",
    "homeUrl": "https://examples.com"
  },
  "createdAt": 1433508108657,
  "updatedAt": 1433508108657
}

Update an OAuth Client

Updates the OAuth client. As soon as the redirect URL is modified, the old URL is not used for users redirection.

PUT /projects/:projectId/applications/:applicationId/oauthClients/:clientId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

OAuthClientDocument (subset)

curl -i -H "Content-type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.com/projects/U2meqbNWegsaQKRRaDUmpssr/applications/UF3Vqb7D6G8EhMwaRYgQ2pFc/oauthClients/AViIrsX3zYYibHr4FZXAEIE0bdD1RLhff7nedB5bT8kr' \
  -d '{
    "name": "Updated Example Client",
    "redirectUrl": "https://examples.com/oauth/updated/callback",
    "customFields": {
      "type": "Web Application",
      "homeUrl": "https://examples.com/updated"
    }
  }'

const projectId = 'Uh5qRBqc4DcmbNbAANtMnrYm';
const applicationId = 'Uh6GfhFnmgScpnxwMsqmbbBk';
const oauthClientId = 'AMWefPQKd1jcQzgizqY2z22x4jhDUaij8d2V72Fq7565r';

const payload = {
  name: 'Updated Example Client',
  redirectUrl: 'https://examples.com/oauth/updated/callback',
  customFields: {
    type: 'Web Application',
    homeUrl: 'https://examples.com/updated',
  },
};

evrythng.api({
  url: `/projects/${projectId}/applications/${applicationId}/oauthClients/${oauthClientId}`,
  apiKey: operatorApiKey,
  method: 'put',
  data: payload,
}).then(console.log);

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "AViIrsX3zYYibHr4FZXAEIE0bdD1RLhff7nedB5bT8kr",
  "name": "Updated Example Client",
  "redirectUrl": "https://examples.com/oauth/updated/callback",
  "customFields": {
    "type": "Web Application",
    "homeUrl": "https://examples.com/updated"
  },
  "createdAt": 1433508108657,
  "updatedAt": 1433937407207
}

Delete an OAuth Client

Delete the OAuth client. After the client is removed, it is not allowed to obtain the Application User access token anymore.

DELETE /projects/:projectId/applications/:applicationId/oauthClients/:clientId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://api.evrythng.com/projects/U2meqbNWegsaQKRRaDUmpssr/applications/UF3Vqb7D6G8EhMwaRYgQ2pFc/oauthClients/AViIrsX3zYYibHr4FZXAEIE0bdD1RLhff7nedB5bT8kr'

const projectId = 'Uh5qRBqc4DcmbNbAANtMnrYm';
const applicationId = 'Uh6GfhFnmgScpnxwMsqmbbBk';
const oauthClientId = 'AMWefPQKd1jcQzgizqY2z22x4jhDUaij8d2V72Fq7565r';

evrythng.api({
  url: `/projects/${projectId}/applications/${applicationId}/oauthClients/${oauthClientId}`,
  apiKey: operatorApiKey,
  method: 'delete,
}).then(() => console.log('Deleted!'));

HTTP/1.1 200 OK

OAuth Authorize

Third party applications can use OAuth 2.0 to authenticate their EVRYTHNG users.

Application owners set up an OAuth client (see above) and receive a clientId. They can then obtain a user token by performing OAuth 2.0 implicit grant type flow, as defined in RFC 6749 specification.

Once the users are authenticated and have agreed to give access to their account, their Application User API key is returned to User Agent using a redirection mechanism.

The client application can use it to interact with the EVRYTHNG API.

OAuth Client Authorize Request

Request a user token using an existing OAuth Client.

GET https://auth.evrythng.com/oauth/authorize?client_id=:clientId
        &redirect_uri=:redirect_uri&response_type=token&state=:state

HTTP/1.1 302 Found
Location: :redirect_uri#access_token=:userApiKey&token_type=apikey&state=:state

Query Parameters

client_id - Ref, Required
ID of the registered OAuth client.
response_type - String, Required
OAuth 2.0 grant type. Only token is supported.
redirect_uri - URI
Possible override of the default redirectUrl defined in the OAuth client object. Only the query string of the URI can be overridden. Any non matching URI will be rejected.
state - String
A custom value forwarded without transformation in the fragment of the redirect response. Recommended to prevent a Cross-Site Request Forgery.

Response Parameters (in fragment)

access_token - API Key
The User API key.
token_type - String
Fixed value: apikey.
state - String
If present in the request, the same value is returned here.
error - String
In case of an unsuccessful (but valid) request, the reason of the failure is returned here.

In case the users refuse to give access to their data, the fragment contains an error=access_denied parameter instead of the access_token. The state parameter is forwarded as-is in all cases:

GET https://auth.evrythng.com/oauth/authorize?client_id=:clientId
        &redirect_uri=:redirect_uri&response_type=token&state=:state

HTTP/1.1 302 Found
Location: :redirect_uri#error=access_denied&state=:state

📘Enterprise Feature

OAuthClientDocument Data Model

Create an OAuth Client

Read All OAuth Clients

Read an OAuth Client

Update an OAuth Client

Delete an OAuth Client

OAuth Authorize

OAuth Client Authorize Request

Query Parameters

Response Parameters (in fragment)

📘
Enterprise Feature