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 ecosystem 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 ecosystem 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.ai/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.ai/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.ai/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"

2.2. Aspecta prompts user for consent

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.ai/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.ai/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.ai/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.ai/v1/users/me
Authorization: Bearer 7/Lvq3XoJkU1oNz8A82v3b6T2I

CURL example

curl -H "Authorization: Bearer 7/Lvq3XoJkU1oNz8A82v3b6T2I" https://api.aspecta.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.ai/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.