SmartVault

APISupport
IntroductionBefore you beginTerminologyGetting started
Authorization
IntroductionOAuth 2.0Authorization Token RequestAuthorization Token ExchangeRefreshing an Access TokenAutonomousPin
Accounts
Entities
User accounts
GroupsFilesFoldersTemplatesEmail templatesAppsErrors

OAuth 2.0

OAuth 2.0 is a standard authorization protocol used to grant third-party applications access to their resources on various services without sharing their login credentials. All requests are done over HTTPS using TLS 1.3.


Overview of the OAuth 2.0 authentication flow.

OAuth 2.0 authentication flow


At a high level the OAuth 2.0 framework will require two steps to authorize a client to perform actions on behalf of an end-user.

  1. Authorization Token Request
  2. Authorization Token Exchange

There is also an optional step that can be used to allow for a "frictionless" integration for an end-user.

  1. Refreshing an Access Token

Authorization Token Request

The Authorization Token Request is an HTTP request sent by the client to the authorization server to request an authorization token. Smartvault’s authorization page can be found at this address. https://my.smartvault.com/users/secure/IntegratedApplications.aspx Typically, the client will formulate this address for the end-user. The end-user will visit this page and allow the client access to perform actions on their behalf.

This call is used to request an authorization token.

Request authorization token
GEThttps://my.smartvault.com/users/secure/IntegratedApplications.aspx?client_id={DEVELOPER_CLIENT_ID}&response_type=code&redirect_uri={REDIRECT_URI_ENCODED}&state={CLIENT_STATE}

The following query parameters should be used to fulfill the request:

response_typestringRequired. This should be set to "code."
client_idstringRequired. This is the client id that the developer account has setup.
redirect_uristringRequired. This is the redirect uri that the developer account has setup. It must match exactly.
statestringOptional. This is a recommended parameter that is used to store some state for the “CLIENTS”. It should also be used as a security measure to prevent cross-site request forgery. RFC 6749 - The OAuth 2.0 Authorization Framework (ietf.org).

Authorization Token Exchange

At this step, the client will have received an authorization code. The client will then need to exchange this code for an access token by sending another HTTP request to the authorization server with the authorization code. The authorization server validates the authorization code and returns an access token if it is valid.

This call is used to request an access token.

Request access token
POST/auto/auth/dtoken/2

The endpoint’s body is as follows:

grant_typestringRequired. This should be set to authorization_code.
codestringRequired. Must be the Authorization Code received in the redirect_uri.
client_secretstringRequired. OAuth 2.0 clients will be required to send the client secret as is. Autonomous clients will use the Authorization Code to create the client secret.
client_idstringRequired. This is the client id that the developer account has setup.

Example request body:

{
    "grant_type": "authorization_code",
    "code": "sm8LgBeRRkK98pqaj4nwfQ",
    "client_secret": "{CLIENT_SECRET}",
    "client_id": "{CLIENT_ID}"
}

Example response body:

{
    "error": {
        "success": true
    },
    "message": {
        "access_token": "4j8nMihehfIdtYtgfsloeeOE7W2aq1",
        "token_type": "bearer",
        "expires_in": 1209600,
        "refresh_token": "iyuU9NRf346YtTdxr57YhpknB8330Hbwsz",
        "refresh_token_expires_in": 2592000,
        "id": "User:bkaTcoKEWkq-d0eyMhmXiw"
    }
}
// Specification Reference: Access Token Successful Response - https://datatracker.ietf.org/doc/html/rfc6749#section-5.1

At this point the client now has an access_token as well as a refresh_token.


Access tokens are issued to access user's data on a third-party service, and can be used to access those resources until they expire or are revoked. The client should store the access token securely and use it until it is no longer valid to avoid unauthorized access to the protected resources. The refresh token is also returned with this call. It can be used by the client to obtain a new access token if the current one expires or has been revoked.

Refreshing an Access Token

Your client will have to handle the case when the Access Token is expired. You will be required to send a POST request to our API and request a new access token.

This call is used to request a refresh token.

Request refresh token
POST/auto/auth/rtoken/2

The body MUST include the following:

grant_typestringRequired. Set to "refresh_token".
refresh_tokenstringRequired. This must be the token received for the end-user you’re requesting access token for.
client_secretstringRequired. OAuth clients will use the client secret that was provided to them when the initial creation of the client. Autonomous clients will use the refresh token to create the client secret. The client_secret here is the signed Refresh Token. SmartVault will validate the signature utilizing the public key provided to smartvault at the creation step of the clientid.

Example request body:

// Content-Type: application/x-www-form-urlencoded
    {
      grant_type="refresh_token"
      client_secret={CLIENT_SECRET}
      refresh_token="tGzv3JOkF0XG5Qx2TlKWIA"
    }

Example response body:

{
    "error": {
        "success": true
    },
    "message": {
        "access_token": "REVMzOEXFM36Y+78HniEs39Cdigo",
        "token_type": "bearer",
        "expires_in": 1209600,
        "refresh_token": "FeWifGjTRR+Zokf46tf",
        "refresh_token_expires_in": 2592000,
        "id": "User:bkaTcoKEWkq-d0eyMhmXiw"
    }
}
//Specification Reference: Refresh Token Successful Response - https://datatracker.ietf.org/doc/html/rfc6749#section-5.1

Refresh Tokens are single-use tokens. After usage they must be replaced as they will no longer be valid.