Skip to content

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.

InformationDescription
App NameThe name of your application.
App DescriptionThe description of your application
App LogoThe logo of your application.
App WebsiteThe website of your application.
App Redirect URIsThe 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.

    ParameterDescription
    response_typeRequired. The field's value MUST be set to code.
    grant_typeRequired. The field's value MUST be set to authorization_code.
    client_idRequired. The client ID for your application, which comes from OAuth 2.0 Client Credentials
    redirect_uriRequired. 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.
    scopeRequired. 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.
    stateRecommended. 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:

    http
    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

    bash
    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"

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.

ErrorDescription
invalid_clientThe OAuth client is incorrect.
redirect_uri_mismatchThe 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:

    http
    https://redirect_url?state=state&code=authorization_code
    • Example:
    http
    https://oauth2.example.com/auth?state=1234xyz&code=57gI-afFfA5Tq9oXhQ9W6RW1zrVrKNABC123XYZ
  • An error response:

    http
    https://redirect_url?state=state&error=access_denied
    • Example:
    http
    https://redirect_url?state=1234xyz&error=access_denied
Error Code

The possible error code are listed below.

ErrorDescription
access_deniedThe user denied access to your application.
invalid_requestThe request is missing a required parameter.
invalid_response_typeThe response_type must be set to code.
unsupported_grant_typeThe grant_type must be set to authorization_code.
invalid_stateThe length of state cannot exceed 32.
invalid_scopeInvalid 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

    ParameterDescription
    grant_typeRequired. The field's value MUST be set to authorization_code.
    codeRequired. The authorization code returned from the initial request.
    client_idRequired. The client ID for your application, which comes from OAuth 2.0 Client Credentials
    client_secretRequired. The client secret for your application, which comes from OAuth 2.0 Client Credentials
    redirect_uriRequired. 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:

    http
    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

    bash
    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:

    FieldDescription
    access_tokenThe access token issued by Aspecta authorization server.
    expires_inThe remaining lifetime of the access token in seconds.
    refresh_tokenA token that you can use to obtain a new access token. Refresh tokens are valid until the user revokes access.
    token_typeThe type of token returned. At this time, this field's value is always set to Bearer.
    scopeThe 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:

    json
    {
        "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:

    FieldDescription
    errorA single error code.
    messageA human-readable description of the error.

    The following example shows an error response:

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

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

    ErrorDescription
    invalid_requestThe request is missing a required parameter.
    invalid_clientThe client info is invalid.

    Any client_id/client_secret is invalid.
    invalid_authorization_codeThe code is invalid.
    unsupported_grant_typeThe grant_type is not supported.

    The grant_type must be set to authorization_code.
    redirect_uri_mismatchThe 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.

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

CURL example

bash
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.

    ErrorDescription
    invalid_tokenThe access token provided is expired, revoked, malformed, or invalid for other reasons.
    missing_authorizationThe authorization in HTTP header is missing.
    insufficient_scopeInsufficient 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

    ParameterDescription
    grant_typeRequired. The field's value MUST be set to refresh_token.
    refresh_tokenRequired. The refresh token returned from the authorization code exchange.
    client_idRequired. The client ID for your application, which comes from OAuth 2.0 Client Credentials
    client_secretRequired. The client secret for your application, which comes from OAuth 2.0 Client Credentials
    scopeOptional. 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:

    http
    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

    bash
    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:

    FieldDescription
    access_tokenThe access token issued by Aspecta authorization server.
    expires_inThe remaining lifetime of the access token in seconds.
    token_typeThe type of token returned. At this time, this field's value is always set to Bearer.
    scopeThe 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:

    json
    {
        "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:

    ErrorDescription
    invalid_requestThe request is missing a required parameter.
    invalid_clientThe client info is invalid.

    Any client_id/client_secret is invalid.
    invalid_grantThe refresh_token is invalid.
    unsupported_grant_typeThe grant_type is not supported.

    The grant_type must be set to refresh_token.
    invalid_scopeThe 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

    ParameterDescription
    tokenRequired. The token that your application wants to get revoked.
    client_idRequired. The client ID for your application, which comes from OAuth 2.0 Client Credentials
    client_secretRequired. The client secret for your application, which comes from OAuth 2.0 Client Credentials

    The following snippet shows a sample request:

    http
    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

    bash
    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:

    ErrorDescription
    invalid_requestThe request is missing a required parameter.
    invalid_clientThe grant info is invalid.

    Any client_id/client_secret is invalid.