Use an OAuth API Token With an Integration

Scopes

Scopes that narrow the access granted to integrated applications can be useful to provide limited access to applications that do not need to write data or perform administrative tasks. Access tokens with scopes that provide Pro Member or Administrator access will expire earlier than those that provide limited (Community Member) access (refresh tokens, explained later in this article, can retrieve a new access token without initiating the entire authorization flow).

Authorization Code Flow

The Authorization Code Flow is a scheme for server-hosted applications with a web browser user interface. The web application redirects a user to the Expert site to verify authentication and authorize the integration between the web application's server-side component(s) and the Expert API. The OAuth 2.0 Authorization Code Flow is a common, industry-supported, authorization scheme for web applications and can be implemented with many existing third-party libraries.  Read the RFC6749 for more details.

GET https://{hostname}/@app/auth/{authid}/token/authorize?client_id={key}&scope={scope}&response_type=code&prompt={prompt}&redirect_uri={redirect_uri}

$ curl --request POST --user {key}:{secret} --data {body} https://{hostname}/@app/auth/{authid}/token/access.json

 // URL encoded form payload
 grant_type=authorization_code&code={code}&redirect_uri={redirect_uri}

Device Code Flow

The Device Code Flow is the scheme for integrations running on devices with no web browser user interface or keyboard, such as television set-top boxes or appliances. In this flow, the integration pauses while the user opens a browser, on their mobile device or computer, to verify authentication on the Expert site and authorize the integration. The Device Code Flow is a newer OAuth 2.0 authorization flow (~2019), as a result, there is less third-party library support than the Authorization Code Flow.

$ curl --request POST --user {key}:{secret} --data {body} https://{hostname}/@app/auth/{authid}/token/device.json 

// URL encoded form payload
scope={scope}

{
    "device_code": "{device_code}",
    "user_code": "{user_code}",
    "verification_uri": "{verification_uri}",
    "verification_uri_complete": "{verification_uri_complete}",
    "expires_in": {expires},
    "interval": {interval}
} 

{
    "device_code": "a722657ed0b1c1bf4d4c099c4b6bbc76fd30ff2c13fdb42d7f33b7394bcb6c7d",
    "user_code": "8cde81c",
    "verification_uri": "https://example.com/@device/1/2d46b20",
    "verification_uri_complete": "https://example.com/@device/1/2d46b20?user_code=8cde81c",
    "expires_in": 3600,
    "interval": 5
}

$ curl --request POST --user {key}:{secret} --data {body} https://{hostname}/@app/auth/{authid}/token/access.json

 // URL encoded form payload
 grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code={device_code}

Access Token Response

The access token data will be returned in application/json; charset=utf-8 format.

{
    "access_token": "{access_token}",
    "refresh_token": "{access_token}",
    "token_type": "bearer",
    "expires_in": "{expires}",
    "scope": "{scope}"
}

Example Access Token JSON

{
    "access_token": "eyJhbGciOiJIUzI1NiIsImtpZCI6ImEzZDFmYWY5YTI0Mzc1ZTFlOTQ1ZjViNGIxMTE0NjNhZGQxY2Y3MDcxMjVkZDMwNTMwMDkzYTU4YjE4NjExYjEiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJodHRwczovL2Jhci5taW5kdG91Y2guYmUiLCJleHAiOjE1ODc2MDc3MDgsImlhdCI6MTU4NzYwNDEwOCwic3ViIjoxLCJpc3MiOiJodHRwczovL2Jhci5taW5kdG91Y2guYmUvQGFwaS9kZWtpL3NlcnZpY2VzLzEiLCJodHRwczovL21pbmR0b3VjaC5jb20vYXV0aHRva2VuL3NlYXRlZCI6ZmFsc2V9.khUs46bJN2znSsgfc09cdU4eBrpGkDUOe7p0IqQl2gs",
    "refresh_token": "1_1587604108_93CE345F6F77E66E7FA5F0E6A69BD1A3D31D938F8F1F19D28996E6CEDD2A976D",
    "token_type": "bearer",
    "expires_in": "3600",
    "scope": "profile"
}

The access token will be used in subsequent requests to the Expert API as a bearer token. A bearer token is the final stage of access validation. The "bearer" of the token effectively has all the rights that the token permits and no further verification is required.

Bearer tokens are used in Expert API requests by adding them to a Bearer Authorization HTTP header:

$ curl --request GET --header 'Authorization: Bearer {access_token}' https://{hostname}/@api/deki/users/current?dream.out.format=json

Using a Refresh Token to Retrieve a New Access Token

If an access token expires, a refresh token can be used to retrieve a new one (provided that the refresh token itself has not expired).

$ curl --request POST --user {key}:{secret} --data {body} https://{hostname}/@app/auth/{authid}/token/access.json

 // URL encoded form payload
 grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code={device_code}

Client-Side Only JavaScript

Pure client-side JavaScript applications, running in a browser, with no server backed application, are presently not supported by this implementation. In the past, OAuth 2.0 allowed public clients (client-side JavaScript, mobile apps, etc) to request an access token using the Implicit Flow. Expert has no plans to implement the Implicit Flow.

In the OAuth ecosystem, due to some inherent security concerns, the Implicit Flow was always considered a stop-gap until a better solution could be devised. That solution is PKCE. However, the Expert OAuth 2.0 system does not yet support this technology.