Introduction

SmartVault supports three forms of authentication: OAuth 2.0 framework with a static key, Autonomous authentication using a public/private key pair, and pin-based authentication.

Each form of authentication pertains to a specific SmartVault API client type (Autonomous, OAuth, Pin).

You can get more information about the authorization methods on the before you begin docs.

Both the OAuth 2 and Autonomous client types use the OAuth 2.0 Authorization framework.

OAuth 2.0

Throughout the authorization documentation, you'll notice three kinds of tokens mentioned:

• the client token,
• authorization token,
• and the delegation token.
  
  In most cases, you will use the delegation token to authenticate. For user management and retrieving a delegation token (more info on each specific section of autonomous authentication and pin based authentication), however, you will instead use the client token.

Client Token

The client token is specific to the Autonomous client type and is used to retrieve the delegation token.

This is a temporary token which can be used by an application to perform administrative tasks.

To request a client token, you will need a self-signed token that uniquely identifies your application so that the SmartVault service can recognize it. After redeeming your self-signed token, SmartVault will hand you the client token and an expiration (generally 24 hours).

Once you are in possession of a client token, you can use it to log on as your client program. You can also exchange this token for a delegation token.

Authorization Token

The authorization token is returned via a redirect URI parameter. It is a token that proves an end-user has started to OAuth authentication flow.

This one time use token can be exchanged for a delegation token such that the holder of the delegation token can perform actions on behalf of the end-user.

Delegation Token

The delegation token is the token that "knows" that you are logged in, allowing you to access the account.
Delegation tokens grant an application access to perform operations on behalf of a SmartVault user.

There are two ways to obtain a delegation token.

• OAuth 2.0 Flow:
  • Obtain a delegation token by exchanging an authorization token.
• Autonomous Flow:
  • Obtain a delegation token by redemming the client token you receive after the user authorizes your application.
    
    

Upon successful request of a delegation token, you will receive the delegation token, the token exipry in seconds, and the user Id. Delegation token lifetime is 14 days. You can obtain a delegation token by redeeming the client token you receive after the user authorizes your application.

If a call is made to SmartVault’s API with an invalid token or expired token, the response will be a 401 status code.

{
    "error": {
        "success": false,
        "error_code": -1593835519,
        "error_text": "Access Denied. Your rights may have changed; please Sign out and Sign back in to correct this problem.",
        "instance_guid": "22fff6c3-90eb-4b18-867d-bd44f65ce332",
        "status_code": 401
    }
}

Authorization Header

The delegation token can be used as a bearer token to authenticate requests. Therefore, you can formulate the Authorization Header as follows:

bearer Q0xJMDAAAAAAAAABUYDOL8O67z2B7oVbKs+V2x2nfGMx3GascjMPJxcGFxvOyg==

Let's assume the following

user's email addres: 'testuser@smartvault.com'
delegation token received: 'Q0xJMDAAAAAAAAABUYDOL8O67z2B7oVbKs+V2x2nfGMx3GascjMPJxcGFxvOyg=='

Build a string as stated above using the user, a colon and the delegation token like:

testuser@smartvault.com:Q0xJMDAAAAAAAAABUYDOL8O67z2B7oVbKs+V2x2nfGMx3GascjMPJxcGFxvOyg==

Then, get the Base64 representation of it, and that would be the token for the "Authorization" request header. e.g.:

basic dGVzdHVzZXJAc21hcnR2YXVsdC5jb206UTB4Sk1EQUFBQUFBQUFBQlVZRE9MOE82N3oyQjdvVmJLcytWMngybmZHTXgzR2FzY2pNUEp4Y0dGeHZPeWc9PQ==