Avaza API supports the common OAuth2 Authentication standard for authenticating your service/app/site to access our APIs.
At first, OAuth2 might seem a little tricky, but it’s a good formalization of a bunch of best practices, and the flexibility and security it brings are worth it.
OAuth2 includes several different ‘flows’ to support different types of services.
The most common is the Authorization Code flow for server-to-server integrations, and the Implicit flow, for connecting to browser/single-page/mobile apps.
Avaza supports both of these.
We support and encourage the use of the PKCE extension on the OAuth2 code flow for Mobile & SPA apps.
Avaza’s ‘Swagger’ API documentation can be found at https://api.avaza.com/
The swagger documentation itself uses the OAuth2 Implicit Flow to allow you to test API calls within the browser.
Avaza also supports the Personal Access Token method for your developers to conveniently authenticate one-off apps and scripts. You can learn more about this method by following this link.
Creating an App
Before you can begin the OAuth process, you must first register a new app with the service. You can register a new OAuth app by navigating to Settings > Manage Developer Apps and then clicking the “Add OAuth App” button. You must have Admin rights to access this feature.
Manage Developer Apps Page
Enter the App Name, Description, App Authentication Client Type, Redirect URL, and the Scopes to which the app would need access to.
OAuth App Creation Popup
Click Save to create the app. The App Client ID and App Secret will be displayed on the screen. Please note that the App Secret will not be displayed again so you must copy and paste it safely. The Secret is used for the Authorization Code flow and adds an extra layer of security for server-to-server implementations.
OAuth Client & Secret Details
You can view all the OAuth 2 Apps on the Developer Apps page. If you wish to update the App Name, Description, Redirect URL, or Access Scopes then simply click the record to open the edit popup. To delete an existing app simply click on the cross icon to the right of the app record. The system will request you to confirm if you really want to delete the app. Once confirmed the app will be deleted.
Server-to-Server apps (OAuth2 Authorization Code flow)
Server-to-server apps are the most common type of app integration. These use the OAuth2 Authorization Code flow.
The general idea is a user is redirected to Avaza where they can log in and verify your app and should be given permission to their account. Then they are redirected back to your app. A temporary, short-lived Authorization Code is issued after the redirect, which your app then uses to directly request a longer-lived Access Token & Refresh Token. If the Access Token expires, you can use the Refresh Token to get a fresh Access Token & Refresh token.
Authorization Codes last for 5 minutes, Access Tokens for 24 hours, and Refresh Tokens for 180 days.
Step 1 – /oauth/authorize
DESCRIPTION
Step 1 of authentication. Create a “Connect Avaza” link, which directs the authenticating user to /oauth2/authorize. This isn’t an API call per se, but rather a web endpoint that lets the user sign in to Avaza and choose whether to grant the application the ability to make API requests on their behalf.
If the user is not currently logged into their Avaza account, they will be first redirected to Authenticate using Avaza’s standard login screen.
Without the user’s authorization in this step, it isn’t possible for your application in step 2 to obtain an access token from /oauth2/access_token.
URL STRUCTURE
https://any.avaza.com/oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=SCOPE
METHOD
GET
PARAMETERS (QueryString)
response_type: required. must be ‘code’ for the server-to-server Authorization Code flow.
client_id: required. The unique Client ID integer value provided by Avaza for your App.
redirect_uri: required. The URL on your server where the user should be redirected to with the response to the authorization code request. If you provided us with a redirect URL when registering your app, then these must match.
scope: required. the URL-encoded set of scopes (i.e. permissions) required by your app. Multiple scopes should be requested by comma separating them. Avaza supports a few different scopes that grant access to particular endpoints. To allow multiple scopes, you would use read_account, and read_contacts. URL encoded, that becomes read_account%2Cread_contacts.
USER SEES
RETURNSAfter the user authorizes the application, they are redirected to your Return URI. If the user granted access, these parameters are passed in the query string (after the ? in the URL):
code The authorization code, which can be used to attain a bearer token by calling
/oauth2/token.state The state content, if any, originally passed to
/oauth2/authorize.
Sample Success response:
[REDIRECT_URI]?code=ABCDEFG&state=[STATE]
ERRORS
In either flow, if an error occurs, including if the user has chosen not to authorize the app, the following parameters will be included in the redirect URI:
error An error code per Section 4.1.2.1 of the OAuth 2.0 spec.
error_description A user-friendly description of the error that occurred.
state The state content, if any, originally passed to
/oauth2/authorize.
Sample Error response:
[REDIRECT_URI]?error=access_denied&error_description=[plain text error message]
Step 2 – /oauth2/token
DESCRIPTIONAn app calls this endpoint to acquire a bearer token once the user has authorized the app.
Calls to /oauth2/token need to be authenticated using the app key and secret. These can be passed as POST parameters (see parameters below).
URL STRUCTURE
https://any.avaza.com/oauth2/token
METHOD
POST
PARAMETERS
code required. The code acquired in step 1 by directing users to
/oauth2/authorize?response_type=code. OR a valid refresh_token obtained from a previous request.grant_type required. The grant type, which must be
authorization_code or refresh_token.client_id required. Provided by Avaza when registering your app.
client_secret required. Provided by Avaza when registering your app.
redirect_uri Only used to validate that it matches the original
/oauth2/authorize, not used to redirect again.
RETURNS
A JSON dictionary including an access token (access_token), integer time till access token expiration in seconds (expires_in), token type (token_type), refresh token (refresh_token)/.
The token type will always be “bearer”.HTTP Response 200 OK code.Sample success response
{"access_token": "ABCDEFG", "expires_in":"86400", "token_type": "bearer", "refresh_token": "12345"}ERRORS
Return an HTTP response header code. e.g. 401 Unauthorized, as well as JSON dictionary response containing error and error_description properties.
Sample error response:
{"error": "invalid_request", "error_description": "You must provide a value for code"}Step 3 – Making API Calls
In Step 2, you obtained an access_token & refresh_token.
The access token is the key to making successful requests to the Avaza API. You’ll store it someplace secure, along with the refresh token. You will use the access token each time your app needs data from Avaza for that account. If you get an unauthorized (401) response from an API call, your access_token has probably expired, and you can use the refresh_token to retrieve a fresh pair of tokens (by calling /oauth2/token with grant type of refresh_token).
Now your app is authorized to use the Avaza API on behalf of your user. When you’d like to make API calls to Avaza, simply include the authorization header, "Authorization: Bearer <YOUR_ACCESS_TOKEN_HERE>", with each request.
The full set of Avaza APIs are documented here: https://api.avaza.com/
Single Page Web Application/Javascript/Mobile Apps (OAuth2 Implicit flow)
Please note that implicit flow for Single Page Applications is no longer security best practice, and it’s better to implement the Oauth2 Code flow + PCKE. When setting up OAuth2 apps, you can identify whether you are using a Sever-To-Server or Mobile/SPA client. For Mobile/SPA the client_secret is not used and not validated. Instead, we encourage PKCE.
These use the OAuth2 Implicit flow.
This is a simplified flow that provides an access_token in a single step and does not require the client's secret (as you wouldn’t have a safe place to store it).
The general idea is a user is redirected to Avaza where they can log in and verify your app and should be given permission to their account. Then they are redirected back to your app. The server redirects back to your Redirect URI and provides an Access Token in the query string. There are no Authorization Codes or Refresh Tokens.
The Access Tokens are valid for 24 hours.
Step 1 – /oauth/authorize
DESCRIPTION
Step 1 of authentication. Create a “Connect Avaza” link, which directs the authenticating user to /oauth2/authorize. This lets the user sign in to Avaza and choose whether to grant the application the ability to make API requests on their behalf.
If the user is not currently logged into their Avaza account, they will be first redirected to Authenticate using Avaza’s standard login screen.
URL STRUCTURE
https://any.avaza.com/oauth2/authorize?response_type=token&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=SCOPE
METHOD
GET
PARAMETERS (QueryString)
response_type: required. must be ‘token’ for the Implicit flow.
client_id: required. The unique Client ID integer value provided by Avaza for your App.
redirect_uri: required. The URL on your server where the user should be redirected to with the response to the token request. If you provided us with a redirect URL when registering your app, then these must match.
scope: required. the URL-encoded set of scopes (i.e. permissions) required by your app. Multiple scopes should be requested by comma separating them. Avaza currently supports read and write scopes. To allow both, you would use read, write. URL encoded, that becomes read%2Cwrite.
USER SEES
RETURNS
After the user authorizes the application, they are redirected to your Return URI.
If the user granted access, these parameters are passed in the URL fragment (after the # in the URL)
access_token The access token which can be used to authenticate subsequent API calls.
token_type currently always “bearer”
expires_in the number of seconds till the access token will expire
state The state content, if any, originally passed to
/oauth2/authorize.
Sample Success response:
[REDIRECT_URI]#access_token=ABCDEFG&token_type=bearer&expires_in=86400&state=[STATE]
ERRORS
In either flow, if an error occurs, including if the user has chosen not to authorize the app, the following parameters will be included in the redirect URI in the query string (after the ?):
error An error code per Section 4.1.2.1 of the OAuth 2.0 spec.
error_description A user-friendly description of the error that occurred.
state The state content, if any, originally passed to
/oauth2/authorize.
Sample Error response:
[REDIRECT_URI]?error=access_denied&error_description=[plain text error message]
Step 2 – Making API Calls
In Step 1, you obtained an access_token.
The access token is the key to making successful requests to the Avaza API. You’ll should store it someplace secure, generally along with the user’s session information. You will use the access token each time your app needs data from Avaza for that account. If you get an unauthorized (401) response from an API call, your access_token has probably expired, and you will need to redirect the user to get a fresh one.
Now your app is authorized to use the Avaza API on behalf of your user. When you’d like to make API calls to Avaza, simply include the authorization header, "Authorization: Bearer <YOUR_ACCESS_TOKEN_HERE>", with each request.
The full set of Avaza APIs are documented here: https://api.avaza.com/