OAuth Authorization Code Process

Available to Public and Private Apps.

Used when your App needs to request access on behalf of a user/account or 3rd party to access user/account data. This is probably the most commonly associated process for OAuth Authentication.

OAuth Authorization Process

Admin Prompt

This is applicable to all Public Evance Apps. An account owner/user must authorise your App as a 3rd party to interact with their account.

Step 1: Request permission

To show the authorisation prompt direct the user to the following URL:

https://{account}.evance.me/admin/oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&state={nonce}&scope={scopes}

{account}
The unique identifier for the account.

{client_id}
Replace with your App's Client ID from your API Credentials.

{redirect_uri}
Replace with the URI you wish to redirect the user to after they have authorised the App. This must be identical to the redirect URI stored in your App's settings.

{nonce}
A random unique unguessable string/number generated by your App for the authorization request. Evance will return this key to your redirect_uri for your App to check.

{scopes}
A space separated list of Scopes.

Step 2: Retrieving your Authorization Code

When the user approves your Apps prompt, they will be redirected to the redirect_uri you specified within your original request.

https://example.com/my-redirect-uri?code={authorization_code}&state={nonce}&account={account}

{authorization_code}
The authorization_code is a one-time code with a short lifetime of only 30 seconds - long enough to retrieve and access_token.

{nonce}
The state parameter supplied by your App in Step 1.

{account}
The Evance account domain e.g. example.evance.me

To verify the authenticity of the request to your App's redirect_uri you should:

Verify that the {nonce} received matches the value you originally sent to Evance in Step 1.
Verify that the {account} is a subdomain of evance.me.

Step 3: Retrieving an Access Token

You may exchange your one-time authorizaton_code for an access_token by making a POST request to the following URL.

POST https://{account}.evance.me/admin/oauth/token.json

Replace {account} with the unique identifier for the account and supply for the following parameters in the body of the request:

client_id
Your App's Client ID from your API Credentials.

client_secret
Your App's secret key - equivalent to a password.

grant_type
Must contain a value of authorization_code

code
The code supplied by the authorisation process in Step 2.

Note: Evance also supports supplying the client_id and client_secret via Basic Auth e.g.:

POST https://{client_id}:{client_secret}@{account}.evance.me/admin/oauth/token.json

A successful request will receive a JSON response from the server similar to the following:

{
    "access_token": "43e213757dd5a224ace6ffc22b8c436219c5830b",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": null,
    "refresh_token": "59461d2abd392f2c6fd36de836f0660ac6214ee5"
}

You now have an access_token with which to make further requests to the Evance API.

access_token
This is the token you will use to interact with API endpoints.

expires_in
Represents the lifetime of the Access Token in seconds. Our Access Tokens expire after a period of 1 hour.

token_type
The token type establishes the security requirements when utilising the token.

scope
The scope of access permitted.

refresh_token
The refresh token has a lifespan of 60 days and may be used to refresh your access token when it expires after 1 hour.

Token Types

Evance does not supply permanent access tokens. Your should be aware of the different token types, their purpose and their longevity.

authorization_code
A one-time code exchanged for an access_token with a lifespan of 30 seconds.

access_token
Used to access data from the API with a lifespan of 1 hour. When the access token expires you may obtain a new access_token using the refresh_token.

refresh_token
Used to obtain a new access_token with a lifespan of 60 days. Evance enforces token rotation. Refresh tokens are replaced with a new refresh_token when used.

Public Prompt

A website user may be prompted to approve access to their specific user data. The steps are the same as those for the Admin Prompt, however the URL changes to the following:

https://{account}.evance.me/oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}

Notice that the admin fragment is dropped from the prompt URL.

OAuth Authorization Code Process

Admin Prompt

Step 1: Request permission

Step 2: Retrieving your Authorization Code

Step 3: Retrieving an Access Token

Public Prompt

Website builder

Themes

Partners

Resources

Evance