Authorization

Using OAuth 2.0 for Web Server Applications

Aspecta APIs use the OAuth 2.0 protocol for authentication and authorization. Aspecta currently only supports OAuth 2.0 web server scenario.

After get your OAuth 2.0 client credentials, your client application requests an access token from the Aspecta authorization server, extracts a token from the response, and sends the token to the Aspecta APIs.

Basic steps

Please follow these basic steps to access an Aspecta API using OAuth 2.0.

1. Obtain OAuth 2.0 client credentials

Contact our business team to obtain your OAuth 2.0 client credentials since our application is currently in beta testing.

For communication efficiency, you would better to provide the following information to us. After get these information we could setup and provide OAuth 2.0 client credentials for you.

Information	Description
App Name	The name of your application.
App Description	The description of your application
App Logo	The logo of your application.
App Website	The website of your application.
App Redirect URIs	The redirect URIs of your application, which are important in OAuth 2.0 security verification.

Our business team will response to you which scopes you can use in the following steps. See the next section for what is scopes.

2. Obtaining OAuth 2.0 access tokens for Aspecta authorization server

Before your application accesses private data using an Aspecta API, it must obtain an access token that grants access to that API. A single access token can grant varying degrees of access to multiple APIs. A variable parameter called scope controls the set of APIs that an access token permits. During the access-token request, your application could send one or more scopes.

Please refer to OAuth 2.0 Scopes for more details.

2.1. Redirect to Aspecta's OAuth 2.0 server

Firstly, you need to create the authorization request. That request sets parameters that identify your application and define the permissions that the user will be asked to grant to your application.

Endpoint
GET https://oauth2.aspecta.id/auth

Request

The following table lists the parameters that you can include in an authorization request.

Parameter	Description
response_type	Required. The field's value MUST be set to `code`.
grant_type	Required. The field's value MUST be set to `authorization_code`.
client_id	Required. The client ID for your application, which comes from OAuth 2.0 Client Credentials
redirect_uri	Required. Determines where the API server redirects the user after the user completes the authorization flow. The value must exactly match one of the authorized redirect URIs for the OAuth 2.0 Client Credentials. If this value doesn't match an authorized redirect URI for the provided client_id you will get a `redirect_uri_mismatch` error.
scope	Required. A space-delimited list of scopes that identify the resources that your application could access on the user's behalf. These values inform the consent screen that Aspecta displays to the user. `Scopes` enable your application to only request access to the resources that it needs while also enabling users to control the amount of access that they grant to your application. The requested scope MUST NOT include any scope NOT originally granted in 1. Obtain OAuth 2.0 Client Credentials.
state	Recommended. Specifies any string value (length <= 32) that your application uses to maintain state between your authorization request and the authorization server's response. The server returns the exact value that you send as a `state=value` pair in the URL query component (?) of the `redirect_uri` after the user consents to or denies your application's access request.

The following snippet shows a sample request:

GET /auth HTTP/1.1
Host: https://oauth2.aspecta.id/auth
Content-Type: application/x-www-form-urlencoded

response_type=code&
grant_type=authorization_code&
client_id=<client_id>&
redirect_uri=https%3A//oauth2.example.com/code&
scope=user&
state=1234xyz

CURL Example

curl -X GET https://oauth2.aspecta.id/auth -d \
    "response_type=code&\
    grant_type=authorization_code&\
    client_id=<client_id>&\
    redirect_uri=https%3A//oauth2.example.com/code&\
    scope=user&\
    state=1234xyz"

In this step, the user decides whether to grant your application the requested access. At this stage, Aspecta displays a consent window that shows the name, description and logo of your application and a summary of the scopes of access to be granted. The user can then consent to grant access to one or more scopes requested by your application or refuse the request.

Your application doesn't need to do anything at this stage as it waits for the response from Aspecta's OAuth 2.0 server indicating whether any access was granted. That response is explained in the following step.

Error

Instead of the expected authentication and authorization flows, requests to Aspecta's OAuth 2.0 authorization endpoint may display error messages to user.

The possible error messages are listed below.

Error	Description
invalid_client	The OAuth client is incorrect.
redirect_uri_mismatch	The redirect uri does NOT match. The `redirect_uri` passed in the authorization request does not match any authorized redirect URIs for OAuth 2.0 Client Credentials.

2.3. Handle the OAuth 2.0 server response

Aspecta OAuth 2.0 server responds to your application's access request by using the URL specified in the request.

If the user approves the access request, then the response contains an authorization code.

If the user does not approve the request or the request is invalid, the response contains an error message code. The authorization code or error message that is returned to the web server appears on the query string, as shown below:

An authorization code response:

https://redirect_url?state=state&code=authorization_code

Example:

https://oauth2.example.com/auth?state=1234xyz&code=57gI-afFfA5Tq9oXhQ9W6RW1zrVrKNABC123XYZ

An error response:

https://redirect_url?state=state&error=access_denied

Example:

https://redirect_url?state=1234xyz&error=access_denied

Error Code

The possible error code are listed below.

Error	Description
access_denied	The user denied access to your application.
invalid_request	The request is missing a required parameter.
invalid_response_type	The `response_type` must be set to `code`.
unsupported_grant_type	The `grant_type` must be set to `authorization_code`.
invalid_state	The length of `state` cannot exceed 32.
invalid_scope	Invalid scope. The requested scope MUST NOT include any scope NOT originally granted in 1. Obtain OAuth 2.0 Client Credentials.

2.4. Exchange authorization code for refresh and access tokens

After your application receives the authorization code, it can exchange the authorization code for an access token.

Endpoint
POST https://oauth2.aspecta.id/token

Request

Parameter	Description
grant_type	Required. The field's value MUST be set to `authorization_code`.
code	Required. The authorization code returned from the initial request.
client_id	Required. The client ID for your application, which comes from OAuth 2.0 Client Credentials
client_secret	Required. The client secret for your application, which comes from OAuth 2.0 Client Credentials
redirect_uri	Required. Determines where the API server redirects the user after the user completes the authorization flow. The value must exactly match one of the authorized redirect URIs for the OAuth 2.0 Client Credentials. If this value doesn't match an authorized redirect URI for the provided client_id you will get a `redirect_uri_mismatch` error.

The following snippet shows a sample request:

POST /token HTTP/1.1
Host: https://oauth2.aspecta.id/token
Authorization: Basic <CLIENT_CREDENTIALS>
Content-Type: application/x-www-form-urlencoded

code=57gI-afFfA5Tq9oXhQ9W6RW1zrVrKNABC123XYZ&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

Where, <CLIENT_CREDENTIALS> is the Base64 encoded string of client_id:client_secret.

CURL Example

curl -X POST https://oauth2.aspecta.id/token \
    -u "<client_id>:<client_secret>" -d \
    "code=57gI-afFfA5Tq9oXhQ9W6RW1zrVrKNABC123XYZ&\
    redirect_uri=https%3A//oauth2.example.com/code&\
    grant_type=authorization_code"

Response

Aspecta responds to this request by returning a JSON object that contains a short-lived access token and a refresh token.

The response contains the following fields:

Field	Description
access_token	The access token issued by Aspecta authorization server.
expires_in	The remaining lifetime of the access token in seconds.
refresh_token	A token that you can use to obtain a new access token. Refresh tokens are valid until the user revokes access.
token_type	The type of token returned. At this time, this field's value is always set to `Bearer`.
scope	The scopes of access granted by the `access_token` expressed as a list of space-delimited, case-sensitive strings, which you requested in the initial request.

The following snippet shows a sample response:

{
    "access_token": "7/Lvq3XoJkU1oNz8A82v3b6T2I",
    "expires_in": 7200,
    "token_type": "Bearer",
    "scope": "user",
    "refresh_token": "1//iF1gEJ9zKdGioZKkZ-wR7MzOYhLcBZxSv5C3JhU"
}

Error

If any requests to Aspecta's OAuth 2.0 token endpoint is invalid, we may report an HTTP 400 error to your application, and the response in JSON format contains an error code and a short readable message of the error. Aspecta OAuth 2.0 server will follow the same error response format in the rest APIs/phases.

The error response contains the following fields:

Field	Description
error	A single error code.
message	A human-readable description of the error.

The following example shows an error response:

{
    "error": "invalid_request",
    "message": "The request is missing a required parameter."
}

The following table lists the possible error responses in this phase:

Error	Description
invalid_request	The request is missing a required parameter.
invalid_client	The client info is invalid. Any `client_id/client_secret` is invalid.
invalid_authorization_code	The `code` is invalid.
unsupported_grant_type	The `grant_type` is not supported. The `grant_type` must be set to `authorization_code`.
redirect_uri_mismatch	The `redirect_uri` does NOT match. The `redirect_uri` passed in the authorization request does not match any authorized redirect URIs for OAuth 2.0 Client Credentials.

3. Use the access token to access Aspecta APIs

After your application obtains an access token, it sends the token to an Aspecta API in an HTTP authorization header. The following example shows a request that passes an access token to the Aspecta API.

GET /drive/v2/files HTTP/1.1
Host: api.aspecta.id/v1/users/me
Authorization: Bearer 7/Lvq3XoJkU1oNz8A82v3b6T2I

CURL example

curl -H "Authorization: Bearer 7/Lvq3XoJkU1oNz8A82v3b6T2I" https://api.aspecta.id/v1/users/me

Please refer to Using REST APIs for more details.

Error

The following table lists the generic authentication errors which may occur in any request to Aspecta's APIs.

Error	Description
invalid_token	The access token provided is expired, revoked, malformed, or invalid for other reasons.
missing_authorization	The authorization in HTTP header is missing.
insufficient_scope	Insufficient access token.

4. Refresh access tokens

Access tokens periodically expire and become invalid tokens for access. To avoid the need for the user to manually re-authenticate every time the access token expires, your application can use a refresh token to obtain a new access token.

Endpoint
POST https://oauth2.aspecta.id/token

Request

Parameter	Description
grant_type	Required. The field's value MUST be set to `refresh_token`.
refresh_token	Required. The refresh token returned from the authorization code exchange.
client_id	Required. The client ID for your application, which comes from OAuth 2.0 Client Credentials
client_secret	Required. The client secret for your application, which comes from OAuth 2.0 Client Credentials
scope	Optional. A space-delimited list of scopes that identify the resources that your application. The requested scope MUST NOT include any scope NOT originally granted in 2.1. Redirect to Aspecta's OAuth 2.0 server, and if omitted is treated as equal to the scope originally granted.

The following snippet shows a sample request:

POST /token HTTP/1.1
Host: https://oauth2.aspecta.id/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <CLIENT_CREDENTIALS>

refresh_token=1//iF1gEJ9zKdGioZKkZ-wR7MzOYhLcBZxSv5C3JhU
grant_type=refresh_token

Where, <CLIENT_CREDENTIALS> is the Base64 encoded string of client_id:client_secret.

CURL Example

curl -X POST https://oauth2.aspecta.id/token \
    -u "<client_id>:<client_secret>" -d \
    "refresh_token=1//iF1gEJ9zKdGioZKkZ-wR7MzOYhLcBZxSv5C3JhU&\
    grant_type=refresh_token"

Response

As long as the user has not revoked the access granted to the application, the token server returns a JSON object that contains a new access token.

The response contains the following fields:

Field	Description
access_token	The access token issued by Aspecta authorization server.
expires_in	The remaining lifetime of the access token in seconds.
token_type	The type of token returned. At this time, this field's value is always set to `Bearer`.
scope	The scopes of access granted by the `access_token` expressed as a list of space-delimited, case-sensitive strings, which you requested in the initial request.

The following snippet shows a sample response:

{
    "access_token": "4/7gI-afFfA5Tq9oXhQ9W6RW1zrVrK",
    "expires_in": 7200,
    "token_type": "Bearer",
    "scope": "user"
}

Error

If any requests to Aspecta's OAuth 2.0 token endpoint is invalid, we may report an HTTP 400 error to your application, and the response contains an error code and a short description of the error.

The following table lists the possible error responses in this phase:

Error	Description
invalid_request	The request is missing a required parameter.
invalid_client	The client info is invalid. Any `client_id/client_secret` is invalid.
invalid_grant	The `refresh_token` is invalid.
unsupported_grant_type	The `grant_type` is not supported. The `grant_type` must be set to `refresh_token`.
invalid_scope	The requested `scope` is invalid, unknown, or malformed. The requested scope MUST NOT include any scope NOT originally granted in 2.1. Redirect to Aspecta's OAuth 2.0 server.

5. Revoke tokens (Optional)

After your application obtains a token of a user, you can request the revocation of a particular token if your application does not need it any longer. Aspecta OAuth 2.0 server revokes and invalidates the given token. If the particular token is a refresh token, the OAuth 2.0 server will invalidate all access tokens based on the same authorization grant. The revoked tokens cannot be used any longer after the revocation.

Endpoint
POST https://oauth2.aspecta.id/revoke

Request

Parameter	Description
token	Required. The token that your application wants to get revoked.
client_id	Required. The client ID for your application, which comes from OAuth 2.0 Client Credentials
client_secret	Required. The client secret for your application, which comes from OAuth 2.0 Client Credentials

The following snippet shows a sample request:

POST /token HTTP/1.1
Host: https://oauth2.aspecta.id/revoke
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <CLIENT_CREDENTIALS>

token=1//iF1gEJ9zKdGioZKkZ-wR7MzOYhLcBZxSv5C3JhU

Where, <CLIENT_CREDENTIALS> is the Base64 encoded string of client_id:client_secret.

CURL Example

curl -X POST https://oauth2.aspecta.id/token \
    -u "<client_id>:<client_secret>" -d \
    "token=1//iF1gEJ9zKdGioZKkZ-wR7MzOYhLcBZxSv5C3JhU"

Response
The API will return an HTTP 200 OK response with an empty response body if the token has been successfully revoked, or the token is invalid.
Note: Invalid tokens do not cause an error response.
Error
If any requests to Aspecta's OAuth 2.0 revoke endpoint is invalid, the API will return an HTTP 400 Bad Request response with a JSON error object containing an error code and description.
The following table lists the possible error responses in this phase:
Error Description
invalid_request The request is missing a required parameter.
invalid_client The grant info is invalid.

Any client_id/client_secret is invalid.

Authorization

Using OAuth 2.0 for Web Server Applications​

Basic steps​

1. Obtain OAuth 2.0 client credentials ​

2. Obtaining OAuth 2.0 access tokens for Aspecta authorization server​

2.1. Redirect to Aspecta's OAuth 2.0 server ​

2.2. Aspecta prompts user for consent​

Error​

2.3. Handle the OAuth 2.0 server response​

Error Code​

2.4. Exchange authorization code for refresh and access tokens​

3. Use the access token to access Aspecta APIs ​

4. Refresh access tokens​

5. Revoke tokens (Optional)​

Using OAuth 2.0 for Web Server Applications

Basic steps

1. Obtain OAuth 2.0 client credentials

2. Obtaining OAuth 2.0 access tokens for Aspecta authorization server

2.1. Redirect to Aspecta's OAuth 2.0 server

2.2. Aspecta prompts user for consent

Error

2.3. Handle the OAuth 2.0 server response

Error Code

2.4. Exchange authorization code for refresh and access tokens

3. Use the access token to access Aspecta APIs

4. Refresh access tokens

5. Revoke tokens (Optional)