1. Overview
  2. Login with OAuth2
  3. Implicit Grant
  4. Authorization Code Grant
  5. Authorization Code Grant (JWT)
  6. Request to Avaya Spaces
  7. Anonymous Guest User

1 Overview

All requests to the Avaya Spaces API must be include an authorization token. To obtain this token a user must be authenticated with Zang Identity. A third party developer can authenticate with Zang Identity by registering as a client application of Avaya Spaces. Once registered OAuth2 will be used to authenticate users and obtain a token for authorized requests to Avaya Spaces.

Note: Recently Google has ended support for OAuth2 flow through web-views on Android and IOS as well as equivalents on Windows and OS X. Since Zang Identity offers Google SSO option for users to sign in, authentication may fail for users using this login option. Seehere for more information.

2 Login with OAuth2

To gain access to a user's Zang account and make requests to Avaya Spaces on their behalf we must direct them to login to Zang Identity using the registered client ID. This is the URL the user should be navigated to:

https://accounts.zang.io/oauth2/authorize?client_id=client_id&redirect_uri=redirect_uri&response_type=response_type&access_type=access_type&scope=https%3A%2F%2Faccounts.zang.io%2Fauth%2Fuserinfo.email+https%3A%2F%2Faccounts.zang.io%2Fauth%2Fuserinfo.profile+https%3A%2F%2Faccounts.zang.io%2Fauth%2Fzangspaces&state=0
client_id
The client ID that was registered
redirect_uri
The redirect URL that was registered
response_type
'token' (for implicit grant), 'code' (for authorization code), 'esjwtcode' (for jwt authorization code)
access_type
'online' (for implicit grant) or 'offline' (for authorization code)
scope
'https://accounts.zang.io/auth/userinfo.email https://accounts.zang.io/auth/userinfo.profile https://accounts.zang.io/auth/zangspaces'
state
Optional but recommended. A csrf token that adds additional security to prevent unauthorized requests (csrf).

When the user lands on this page they will be asked to login with one of the following methods:

  • Zang account
  • Google account
  • Office365 account
  • Salesforce account
  • Avaya account

After logging in they will be redirected once more to https://accounts.zang.io/oauth2/authorize/confirm where they will choose to allow or deny the following permissions to your application:

  • View and update user email information
  • View user detail information
  • Call Avaya Spaces APIs

The next steps are determined by your chosen OAuth2 authorization method (Implicit grant or Authorization code), which was specified by the query parametersresponse_type and access_type.


Typically web and mobile applications will want to use Implicit grant. Pure server side applications may prefer to use Authorization code.

To access Zang Office APIs use Authorization Code Grant (JWT) method.

3 Implicit Grant

Once the user has authenticated with Zang Identity and allowed your application as specified above in section 2. Zang Identity will redirect the user to the registered redirect URL specified and will include the access token necessary to make authorized requests to Avaya Spaces. The redirect will look like this:

https://mywebsite.com/redirecthere/#access_token=access_token&expires_in=expires_in&id_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZ3h6Zm05dVpYTnVZVEl3TVRSeUVRc1NCRlZ6WlhJWWdJREFfYl9RblFzTSIsImlzcyI6Im9uZXNuYS5jb20iLCJleHAiOjE0OTM4NDA3MjAsImlkX3Rva2VuX3ZlcnNpb24iOiIxLjAiLCJpYXQiOjE0OTM4MzcxMjAsImVtYWlsIjoicGF0cmlja2hhbkBlc25hLmNvbSIsImF1ZCI6IlRlc3RDbGllbnRJZCJ9.CyV3qM6fb_zMTVcSw1gv7DVxz8dkoAyK_Bb994p_57g&state=3
access_token
The authorization token to be included with requests to Avaya Spaces.
expires_in
The remaining lifetime of this access token in seconds. Note: Token may expire sooner.
state
Verify with state value sent in section 2 (csrf).

You should store the access_token since you will need to include it for every request to Avaya Spaces. Proceed to section 6to learn how to make requests to the Avaya Spaces API.

4 Authorization Code Grant

Once the user has authenticated with Zang Identity and allowed your application as specified in section 2. Zang Identity will redirect the user to the registered redirect URL specified and will include a code. This code will be used to obtain the authorization token. For example:

https://mywebsite.com/redirecthere/#code=code&state=3
code
This code will be used to obtain our authorization code for this user.
state
Verify with state value sent in section 2 (csrf).

Now we will obtain our access token using our: client ID, secret and the code (we just obtained). Since the secret should only be stored on the server and sent only between your application server and Zang Identity directly, we will have to request our access token by making a request on the server and not using the client. Unlike our previous requests to Zang Identity, this is a POST request to https://accounts.zang.io/oauth2/access_token, with the following form body:

grant_type=authorization_code&client_id=client_id&client_secret=client_secret&code=code&redirect_uri=redirect_uri
grant_type
Should always be 'authorization_code'. Unless obtaining a refresh token, then use 'refresh_token'
client_id
The Client ID provided during registration.
client_secret
The secret provided during registration.
code
The authorization code provided in the previous step.
redirect_uri
The registered redirect URL.

If this request was successful then Zang Identity will return the access token. The response should look like this:

{
    "access_token": "7925452a9cf7f01f9fa874cd56e9db94774bf87e",
    "scope": "https://accounts.zang.io/auth/userinfo.email https://accounts.zang.io/auth/userinfo.profile https://accounts.zang.io/auth/zangspaces",
    "expires_in": 3600,
    "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZ3h6Zm05dVpYTnVZVEl3TVRSeUVRc1NCRlZ6WlhJWWdJREFfYl9RblFzTSIsImlzcyI6Im9uZXNuYS5jb20iLCJleHAiOjE0OTM4NTAyNjIsImlkX3Rva2VuX3ZlcnNpb24iOiIxLjAiLCJpYXQiOjE0OTM4NDY2NjIsImVtYWlsIjoicGF0cmlja2hhbkBlc25hLmNvbSIsImF1ZCI6IlRlc3RDbGllbnRJZCJ9.RGy9P3THwjmzbArx4E3Ggos9bHIY30nnFYNWd1rAZss"
}
access_token
The authorization token to be included with requests to Avaya Spaces.
scope
The scope for which the token is granted.
expires_in
The remaining lifetime of this access token in seconds. Note: Token may expire sooner.
id_token
Use this token to refresh the access_token when it expires.

You should store the access_token since you will need to include it for every request to Avaya Spaces. Proceed to section 6 to learn how to make requests to the Avaya Spaces API.

Note: To refresh the access token, make another POST request to https://accounts.zang.io/oauth2/access_token with the grant_type set to refresh_token. You may want to refresh the access token before it expires to minimize failed requests and improve performance.

5 Authorization Code Grant (JWT)

This authorization method is a modified OAuth2 flow. This modified method is necessary to be able to authenticate to Zang Office APIs since standard OAuth2 is not currently supported. The JWT token cannot be refreshed, a new token must be obtained after expiry.

Once the user has authenticated with Zang Identity and allowed your application as specified in section 2. Zang Identity will redirect the user to the registered redirect URL specified and will include a code. This code will be used to obtain the authorization token. For example:

https://mywebsite.com/redirecthere/#code=code&state=3
code
This code will be used to obtain our authorization code for this user.
state
Verify with state value sent in section 2 (csrf).

Now we will obtain our access token using our: client ID, secret and the code (we just obtained). Since the secret should only be stored on the server and sent only between your application server and Zang Identity directly, we will have to request our access token by making a request on the server and not using the client. Unlike our previous requests to Zang Identity, this is a POST request to https://accounts.zang.io/oauth2/access_token, with the following form body:

grant_type=authorization_code&client_id=client_id&client_secret=client_secret&code=code&redirect_uri=redirect_uri
grant_type
Should always be 'authorization_esjwtcode'.
client_id
The Client ID provided during registration.
client_secret
The secret provided during registration.
code
The authorization code provided in the previous step.
redirect_uri
The registered redirect URL.

If this request was successful then Zang Identity will return the access token. The response should look like this:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJvcmlnX2lhdCI6MTUxMzM3MzEwNCwiZXhwIjoxNTE1OTY1MTA0LCJwdWJsaWNrZXlpZCI6ImFoRmtaWFotYjI1bGMyNWhkR1Z6ZEdsdVozSWFDeElOUjBwM2RGQjFZbXhwWTB0bGVSaUFnSUNBZ01DdkNndyIsInByb2R1Y3RfdHlwZSI6ImFjY291bnRzIiwidmVyIjoiMi4wIiwiaXNzIjoibG9jYWxob3N0IiwidXNlcl9pZCI6ImFoRmtaWFotYjI1bGMyNWhkR1Z6ZEdsdVozSVJDeElFVlhObGNoaUFnSUNBZ0lDQUNndyIsInNjb3BlIjoiaHR0cHM6Ly93d3cub25lc25hLmNvbS9hdXRoL3VzZXJpbmZvLnByb2ZpbGUgaHR0cHM6Ly93d3cub25lc25hLmNvbS9hdXRoL3VzZXJpbmZvLmVtYWlsIiwidXNlcl9pZF9zaWciOiJUNEdPSENmYi1HUjgxUkdNSlRQUk9UQ01IdDVwNHNVZ2I5NmFoSmhxd2k4In0.CheW57yiWm7cz3e1mDzuUjCJXFKO0y4TzP5NG_8aPYNEZmEOs793m5ruy1bj78GjlGZfdckMEhCJw5ksEYOi16V_jYqKMY80_UcyINqARpaHjwVgu_cemDz4Qaja0-LeqtK9u2dHuscFuRgQFPP-rvKVsxZSj9GwsRukOq6wGX3ixR06d1thzKWwieey--4V2TW7158ALIJFQOoCaCnuzhZ2iFNSGkrCHP8ea0F3JiaPzS_15Q8c8ApmPJ15bxTRjXFAiKhQ5iH9gZUr_ank3R1f4JSLu7cnF0t_YTDcEF1gfqAmE95qm9zmZYxH5sOAeQj6iTGPV3vTYDUAtJk1ow",
    "scope": "https://accounts.zang.io/auth/userinfo.email https://accounts.zang.io/auth/userinfo.profile https://accounts.zang.io/auth/zangspaces",
    "expires_in": 2591999,
    "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZ3h6Zm05dVpYTnVZVEl3TVRSeUVRc1NCRlZ6WlhJWWdJREFfYl9RblFzTSIsImlzcyI6Im9uZXNuYS5jb20iLCJleHAiOjE0OTM4NTAyNjIsImlkX3Rva2VuX3ZlcnNpb24iOiIxLjAiLCJpYXQiOjE0OTM4NDY2NjIsImVtYWlsIjoicGF0cmlja2hhbkBlc25hLmNvbSIsImF1ZCI6IlRlc3RDbGllbnRJZCJ9.RGy9P3THwjmzbArx4E3Ggos9bHIY30nnFYNWd1rAZss"
}
access_token
The authorization token to be included with requests to Avaya Spaces.
scope
The scope for which the token is granted.
expires_in
The remaining lifetime of this access token in seconds. Note: Token may expire sooner.
id_token
Use this token to refresh the access_token when it expires.

You should store the access_token since you will need to include it for every request to Avaya Spaces. Proceed to section 6 to learn how to make requests to the Avaya Spaces API.

6 Request to Avaya Spaces

Now that you have registered your client application and have obtained an authorization token you can make requests to the Avaya Spaces api by including the access_token in the HTTP headers like so:

$.ajax({
    url: 'API_ENDPOINT', //example: https://spacesapis.zang.io/api/users/me
    headers: {
        Authorization: 'bearer access_token'  // or 'jwt access_token'
    },
    type: 'GET',
    success: function(response) {
        console.log('Request successful' + response);
    }
});

You can also use the access token to establish a socket.io connection. See the socket.io guide for more information.

7 Anonymous Guest User

Avaya Spaces users may want to invite people to collaborate with them on Avaya Spaces that are not authorized users. For this reason anonymous guest users can access limited feeatures in Avaya Spaces. To obtain a JWT for an anonymous user use the following API endpoint /api/anonymous/authA JWT will be returned that can be used to authorize requests to Avaya Spaces APIs, this token is only valid for 24 hours. See section 6 for information on sending authorized requests to Avaya Spaces with JWT.

Note that anonymous guests can only participate in spaces to which they are invited (they cannot create new spaces). They only have guest level access in a space and cannot be promoted to member or admin.