Use OAuth 2.0 when other people connect your app to their Avaza account. Each person signs in with their own Avaza login and approves your app. Your app then gets tokens that act as that person, with no password shared. For your own scripts, a personal access token is simpler: see getting started with the Avaza API.

Avaza supports the authorisation code flow, with the optional PKCE extension, and the older implicit flow.

Endpoint

URL

Authorisation

https://any.avaza.com/oauth2/authorize

Token

https://any.avaza.com/oauth2/token

API requests

https://api.avaza.com/

Register your app

Only Administrators can register apps.

  1. Go to Settings › Developer Apps & API Access, stay on the OAuth tab, and click Add OAuth App.

  2. Enter the App Name, which people see when they approve your app, and an optional App Description.

  3. Under App Authentication Client Type, choose Server-To-Server if your server can keep a client secret safe. Choose Mobile and SPA clients for apps that run on a phone or in the browser: they don't use a secret and should use PKCE instead.

  4. Enter the Redirect URL, where Avaza sends people back after they approve or deny. It can't contain a # fragment.

  5. Under Select Access Scopes, tick every scope your app may ask for, then click Save.

    The empty Add OAuth App popup with App Name, App Description, App Authentication Client Type (Server-To-Server or Mobile and SPA clients), Redirect URL and the Select Access Scopes list, with Save and Cancel

  6. Copy the App Client_ID and the Secret. Avaza shows the secret only once.

To change an app, click it in the list. Scope changes only apply to people who authorise the app after the change. To make everyone re-authorise, contact Avaza support. To delete an app, click the cross at the end of its row and confirm. That also removes the tokens it was given in your account.

Let other Avaza accounts connect your app

An app you register can only connect to your own Avaza account. If someone in another account tries to approve it, Avaza refuses with access_denied. There's no setting for this in Avaza: Avaza support does it for you, in two separate steps.

  1. Make the app public. Contact Avaza support and ask for your app to be made public. Include its App Client_ID. Once it's public, people in any Avaza account can approve it with the steps below.
  2. List it in the App Marketplace (optional). A public app isn't listed in Settings › App Marketplace automatically. If you'd like it listed, ask Avaza support. Avaza reviews each request. See the Avaza App Marketplace.

Step 1: send the person to Avaza

Link to the authorisation URL with these query parameters, all on one line:

https://any.avaza.com/oauth2/authorize?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyourapp.example.com%2Fcallback
  &scope=read_projects%20write_timesheets
  &state=RANDOM_STRING
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  • response_type: code.
  • client_id: your app's Client_ID.
  • redirect_uri: must match the registered Redirect URL exactly. If you leave it out, Avaza uses the registered one.
  • scope: optional. Separate scopes with spaces or commas. Each one must be ticked on the app. Leave it out to ask for all of the app's scopes. The older shorthand read and write still works: read stands for every read scope plus webhook_notifications, and write for every write scope, so the app needs all of them ticked.
  • state: optional but recommended. A random value that comes back unchanged, so you can reject forged responses.
  • code_challenge and code_challenge_method: for PKCE. Use S256. Without a method, Avaza assumes plain.

The person signs in if they aren't already, then sees Grant your app access to your Avaza account? with the list of scopes. They click Grant Access to Avaza or Deny access to Avaza.

Most roles can approve an app, including company contacts with Project Collaborator or Timesheet/Expense User. People whose only roles are Chat User, Schedule Viewer or Customer Finances can't.

Step 2: swap the code for tokens

After approval, Avaza redirects to your Redirect URL with code, state and accountid (the Avaza account that was connected):

https://yourapp.example.com/callback?code=AUTH_CODE&state=RANDOM_STRING&accountid=12345

The code works once, within 5 minutes. From your server, post it to the token endpoint as a form:

curl -X POST https://any.avaza.com/oauth2/token \
  -d grant_type=authorization_code \
  -d code=AUTH_CODE \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code_verifier=YOUR_CODE_VERIFIER

Send client_secret for Server-To-Server apps only, and code_verifier only if you sent a code_challenge. The response includes:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "expires_in": 86400,
  "token_type": "bearer",
  "refresh_token": "YOUR_REFRESH_TOKEN"
}

Store both tokens somewhere safe. Then call the API with the access token in the header Authorization: Bearer YOUR_ACCESS_TOKEN.

Keep the tokens fresh

Access tokens last 24 hours (expires_in is in seconds). Refresh tokens last 180 days. When the access token expires, or the API answers 401, get a new pair:

curl -X POST https://any.avaza.com/oauth2/token \
  -d grant_type=refresh_token \
  -d refresh_token=YOUR_REFRESH_TOKEN \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

Each refresh returns a new access token and a new refresh token, and the old refresh token stops working. Save the new one every time. If the refresh token has expired or was already used, send the person through step 1 again.

Don't keep calling the API with an expired token. Failed authentication counts per IP address, and after 100 failures that address is blocked for 15 minutes. See API rate limits.

When something goes wrong

At the authorisation step, Avaza redirects to your Redirect URL with error and error_description:

  • access_denied: the person clicked Deny, their roles don't allow API access, or the app belongs to another Avaza account.
  • invalid_scope: a requested scope isn't ticked on the app.
  • invalid_request: the redirect_uri doesn't match the registered Redirect URL.
  • unsupported_response_type: response_type isn't code or token.

If the client_id is unknown, Avaza shows an error page instead of redirecting.

At the token endpoint, you get HTTP 400 or 401 with JSON such as {"error": "invalid_grant", "error_description": "Authorization Code has expired"}. The common codes are invalid_request (a missing parameter), invalid_client (unknown client_id or wrong secret) and invalid_grant (a code or refresh token that is wrong, used or expired).

Browser and mobile apps

Register the app as Mobile and SPA clients and use the code flow with PKCE, without a secret.

The implicit flow still works but is no longer recommended. Send response_type=token, and Avaza returns the token in the URL fragment: #access_token=...&token_type=bearer&expires_in=86400&state=.... The token lasts 24 hours and there's no refresh token, so the person has to approve again after that.

What a connected app can see

A connected app can only use its scopes, and only sees what the person who approved it can see in Avaza. Administrators can restrict it further under API permissions, and each app has its own rate limits on each account. See getting started with the Avaza API and webhook notifications.