NAV Navigation
Shell Node.js HTTP

Alvaria Cloud® Authorization REST API v3.1

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Overview

The Alvaria Cloud® MyAccount Authorization & Authentication REST APIs enable developers to get access to other available APIs.

Information on Dynamic Client Registration can be found in RFC 7591 and RFC 7592

Note: The domain in the base URL corresponds to the Alvaria™ website that hosts the API. Presently, it differs by cloud vendor.

Table 1: base URLs for each cloud solution

Cloud Vendor Details Domain
Amazon Web Service (AWS) via.aspect-cloud.net
Amazon Web Service (AWS) tri (workforce only) wos.alvaria.cloud
GCP apc.alvaria.cloud

Base URLs:

License: License: Creative Commons Attribution 4.0 International Public License

Authentication

Table 2: access_token endpoints for each region

Cloud Vendor Region tokenHost
Amazon Web Service (AWS) US myaspect.id.aspect-cloud.net
Amazon Web Service (AWS) Europe myaspect.eu.id.aspect-cloud.net
Amazon Web Service (AWS) UK myaspect.uk.id.aspect-cloud.net
Amazon Web Service (AWS) Canada myaspect.ca.id.aspect-cloud.net
Amazon Web Service (AWS) US-East (tri) myaccount.tri1.wss.alvaria.cloud
GCP DSM myaccount.dsm.sre.alvaria.cloud 
- Flow: client crendentials

- Token URL = [https://tokenHost/tokenservice/oauth2/access_token](https://tokenHost/tokenservice/oauth2/access_token)
Scope Scope Description
myaccount.clients.list Retrieve a list of OAuthClient resources
myaccount.clients.create Create OAuthClient resource
myaccount.clients.modify Update OAuthClient resource
myaccount.clients.view Retrieve OAuthClient resource
myaccount.clients.delete Delete OAuthClient resource

OAuth2 Clients

Operations Relating Dynamic Client Registration Management, as defined in: RFC 7591 & RFC 7592

Get list of OAuthClient metadata

Code samples

# You can also use wget
curl -X GET https://orgId.domain/via/v1/organizations/{orgId}/oauth/clients \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'x-api-key: API_KEY'


const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}',
  'x-api-key':'API_KEY'
};

fetch('https://orgId.domain/via/v1/organizations/{orgId}/oauth/clients',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});


GET https://orgId.domain/via/v1/organizations/{orgId}/oauth/clients HTTP/1.1
Host: orgid.domain
Accept: application/json

GET /via/v1/organizations/{orgId}/oauth/clients

Get list of OAuthClient metadata, Response will NOT contain client_secret.

Parameters

Name In Type Required Description
orgId path string true Name of a customer organization.

Example responses

200 Response

[
  {
    "client_id": "2DxowL00RyG6OZdbYNaQs3R",
    "client_id_issued_at": 1659104786,
    "client_secret_expires_at": 0,
    "redirect_uris": [
      "https://client.example.org/callback",
      "https://client.example.org/callback2"
    ],
    "registration_client_uri": "https://server.example.com/via/v1/organizations/myorg/oauth/clients/2DxowL00RyG6OZdbYNaQs3R",
    "grant_types": [
      "authorization_code",
      "client_credentials",
      "refresh_token"
    ],
    "response_types": [
      "code",
      "id_token"
    ],
    "client_name": "CUSTOMER_ORG_API_CLIENT",
    "scope": "myaspect.users myaspect.teams myaspect.teams.write",
    "x_api_key": "7FFAC9BB21628320FAEBC5786F152B0F2309D6528C7284B5E3E34E1AFE204A39",
    "client_description": "Fully-Authorized Client",
    "contacts": [
      "name1@company1.com",
      "name2@company2.com"
    ]
  }
]

Responses

Status Meaning Description Schema
200 OK Successful response ListOAuthClientResponseMinusSecret
400 Bad Request Bad Request None
401 Unauthorized Unauthorized None
403 Forbidden Forbidden None
404 Not Found Resource Not Found None
405 Method Not Allowed Method Not Allowed None
429 Too Many Requests Throttled None
500 Internal Server Error Internal server error None

Generates a new OAuthClient

Code samples

# You can also use wget
curl -X POST https://orgId.domain/via/v1/organizations/{orgId}/oauth/clients \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'x-api-key: API_KEY'


const fetch = require('node-fetch');
const inputBody = {
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"
  ],
  "grant_types": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "response_types": [
    "code",
    "id_token"
  ],
  "client_name": "CUSTOMER_ORG_API_CLIENT",
  "scope": "myaspect.users myaspect.teams myaspect.teams.write",
  "client_description": "Fully-Authorized Client",
  "contacts": [
    "name1@company1.com",
    "name2@company2.com"
  ]
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}',
  'x-api-key':'API_KEY'
};

fetch('https://orgId.domain/via/v1/organizations/{orgId}/oauth/clients',
{
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});


POST https://orgId.domain/via/v1/organizations/{orgId}/oauth/clients HTTP/1.1
Host: orgid.domain
Content-Type: application/json
Accept: application/json

POST /via/v1/organizations/{orgId}/oauth/clients

Generates a new OAuthClient

Body parameter

{
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"
  ],
  "grant_types": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "response_types": [
    "code",
    "id_token"
  ],
  "client_name": "CUSTOMER_ORG_API_CLIENT",
  "scope": "myaspect.users myaspect.teams myaspect.teams.write",
  "client_description": "Fully-Authorized Client",
  "contacts": [
    "name1@company1.com",
    "name2@company2.com"
  ]
}

Parameters

Name In Type Required Description
body body OAuthClientRequest true OAuth Client request model as defined here [https://datatracker.ietf.org/doc/html/rfc7591]
orgId path string true Name of a customer organization.

Example responses

201 Response

{
  "client_id": "2DxowL00RyG6OZdbYNaQs3R",
  "client_secret": "P9dvyTNFyI7RCaRRmRp3E3FR0WV0jSUDMAo",
  "client_id_issued_at": 1659104786,
  "client_secret_expires_at": 0,
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"
  ],
  "registration_client_uri": "https://server.example.com/via/v1/organizations/myorg/oauth/clients/2DxowL00RyG6OZdbYNaQs3R",
  "grant_types": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "response_types": [
    "code",
    "id_token"
  ],
  "client_name": "CUSTOMER_ORG_API_CLIENT",
  "scope": "myaspect.users myaspect.teams myaspect.teams.write",
  "x_api_key": "7FFAC9BB21628320FAEBC5786F152B0F2309D6528C7284B5E3E34E1AFE204A39",
  "client_description": "Fully-Authorized Client",
  "contacts": [
    "name1@company1.com",
    "name2@company2.com"
  ]
}

Responses

Status Meaning Description Schema
201 Created Created OAuthClientResponse
400 Bad Request Bad Request None
401 Unauthorized Unauthorized None
403 Forbidden Forbidden None
404 Not Found Resource Not Found None
405 Method Not Allowed Method Not Allowed None
429 Too Many Requests Throttled None
500 Internal Server Error Internal server error None

Get an OAuthClient metadata

Code samples

# You can also use wget
curl -X GET https://orgId.domain/via/v1/organizations/{orgId}/oauth/clients/{clientId} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'x-api-key: API_KEY'


const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}',
  'x-api-key':'API_KEY'
};

fetch('https://orgId.domain/via/v1/organizations/{orgId}/oauth/clients/{clientId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});


GET https://orgId.domain/via/v1/organizations/{orgId}/oauth/clients/{clientId} HTTP/1.1
Host: orgid.domain
Accept: application/json

GET /via/v1/organizations/{orgId}/oauth/clients/{clientId}

Get an OAuthClient metadata, Response will NOT contain client_secret.

Parameters

Name In Type Required Description
orgId path string true Name of a customer organization.
clientId path string true Identifier of an OAuthClient.

Example responses

200 Response

{
  "client_id": "2DxowL00RyG6OZdbYNaQs3R",
  "client_id_issued_at": 1659104786,
  "client_secret_expires_at": 0,
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"
  ],
  "registration_client_uri": "https://server.example.com/via/v1/organizations/myorg/oauth/clients/2DxowL00RyG6OZdbYNaQs3R",
  "grant_types": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "response_types": [
    "code",
    "id_token"
  ],
  "client_name": "CUSTOMER_ORG_API_CLIENT",
  "scope": "myaspect.users myaspect.teams myaspect.teams.write",
  "x_api_key": "7FFAC9BB21628320FAEBC5786F152B0F2309D6528C7284B5E3E34E1AFE204A39",
  "client_description": "Fully-Authorized Client",
  "contacts": [
    "name1@company1.com",
    "name2@company2.com"
  ]
}

Responses

Status Meaning Description Schema
200 OK Successful response OAuthClientResponseMinusSecret
400 Bad Request Bad Request None
401 Unauthorized Unauthorized None
403 Forbidden Forbidden None
404 Not Found Resource Not Found None
405 Method Not Allowed Method Not Allowed None
429 Too Many Requests Throttled None
500 Internal Server Error Internal server error None

Update an OAuthClient metadata

Code samples

# You can also use wget
curl -X PUT https://orgId.domain/via/v1/organizations/{orgId}/oauth/clients/{clientId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'x-api-key: API_KEY'


const fetch = require('node-fetch');
const inputBody = {
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"
  ],
  "grant_types": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "response_types": [
    "code",
    "id_token"
  ],
  "client_name": "CUSTOMER_ORG_API_CLIENT",
  "scope": "myaspect.users myaspect.teams myaspect.teams.write",
  "client_description": "Fully-Authorized Client",
  "contacts": [
    "name1@company1.com",
    "name2@company2.com"
  ]
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}',
  'x-api-key':'API_KEY'
};

fetch('https://orgId.domain/via/v1/organizations/{orgId}/oauth/clients/{clientId}',
{
  method: 'PUT',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});


PUT https://orgId.domain/via/v1/organizations/{orgId}/oauth/clients/{clientId} HTTP/1.1
Host: orgid.domain
Content-Type: application/json
Accept: application/json

PUT /via/v1/organizations/{orgId}/oauth/clients/{clientId}

Update an OAuthClient metadata, Response will NOT contain client_secret.

Body parameter

{
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"
  ],
  "grant_types": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "response_types": [
    "code",
    "id_token"
  ],
  "client_name": "CUSTOMER_ORG_API_CLIENT",
  "scope": "myaspect.users myaspect.teams myaspect.teams.write",
  "client_description": "Fully-Authorized Client",
  "contacts": [
    "name1@company1.com",
    "name2@company2.com"
  ]
}

Parameters

Name In Type Required Description
body body OAuthClientRequest true OAuth Client request model as defined here [https://datatracker.ietf.org/doc/html/rfc7591]
orgId path string true Name of a customer organization.
clientId path string true Identifier of an OAuthClient.

Example responses

200 Response

{
  "client_id": "2DxowL00RyG6OZdbYNaQs3R",
  "client_id_issued_at": 1659104786,
  "client_secret_expires_at": 0,
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"
  ],
  "registration_client_uri": "https://server.example.com/via/v1/organizations/myorg/oauth/clients/2DxowL00RyG6OZdbYNaQs3R",
  "grant_types": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "response_types": [
    "code",
    "id_token"
  ],
  "client_name": "CUSTOMER_ORG_API_CLIENT",
  "scope": "myaspect.users myaspect.teams myaspect.teams.write",
  "x_api_key": "7FFAC9BB21628320FAEBC5786F152B0F2309D6528C7284B5E3E34E1AFE204A39",
  "client_description": "Fully-Authorized Client",
  "contacts": [
    "name1@company1.com",
    "name2@company2.com"
  ]
}

Responses

Status Meaning Description Schema
200 OK Successful response OAuthClientResponseMinusSecret
400 Bad Request Bad Request None
401 Unauthorized Unauthorized None
403 Forbidden Forbidden None
404 Not Found Resource Not Found None
405 Method Not Allowed Method Not Allowed None
429 Too Many Requests Throttled None
500 Internal Server Error Internal server error None

Delete an OAuthClient

Code samples

# You can also use wget
curl -X DELETE https://orgId.domain/via/v1/organizations/{orgId}/oauth/clients/{clientId} \
  -H 'Authorization: Bearer {access-token}' \
  -H 'x-api-key: API_KEY'


const fetch = require('node-fetch');

const headers = {
  'Authorization':'Bearer {access-token}',
  'x-api-key':'API_KEY'
};

fetch('https://orgId.domain/via/v1/organizations/{orgId}/oauth/clients/{clientId}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});


DELETE https://orgId.domain/via/v1/organizations/{orgId}/oauth/clients/{clientId} HTTP/1.1
Host: orgid.domain

DELETE /via/v1/organizations/{orgId}/oauth/clients/{clientId}

Delete an OAuthClient metadata.

Parameters

Name In Type Required Description
orgId path string true Name of a customer organization.
clientId path string true Identifier of an OAuthClient.

Responses

Status Meaning Description Schema
204 No Content No Content None
400 Bad Request Bad Request None
401 Unauthorized Unauthorized None
403 Forbidden Forbidden None
404 Not Found Resource Not Found None
405 Method Not Allowed Method Not Allowed None
429 Too Many Requests Throttled None
500 Internal Server Error Internal server error None

Schemas

OAuthClientRequest

{
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"
  ],
  "grant_types": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "response_types": [
    "code",
    "id_token"
  ],
  "client_name": "CUSTOMER_ORG_API_CLIENT",
  "scope": "myaspect.users myaspect.teams myaspect.teams.write",
  "client_description": "Fully-Authorized Client",
  "contacts": [
    "name1@company1.com",
    "name2@company2.com"
  ]
}

Properties

Name Type Required Restrictions Description
redirect_uris [string] false none Array of redirection URI strings for use in redirect-based flows such as the authorization code flow.
grant_types [string] false none Array of OAuth 2.0 grant type strings that the client can use at the token endpoint.
response_types [string] false none Array of the OAuth 2.0 response type strings that the client can use at the authorization endpoint.
client_name string false none Human-readable string name of the client
scope string true none String containing a space-separated list of OAuth 2.0 scope values
client_description string false none Human Readable Description of a client.
contacts [string] false none Array of the OAuth 2.0 response type strings representing ways to contact people responsible for this client, typically email addresses.

OAuthClientResponse

{
  "client_id": "2DxowL00RyG6OZdbYNaQs3R",
  "client_secret": "P9dvyTNFyI7RCaRRmRp3E3FR0WV0jSUDMAo",
  "client_id_issued_at": 1659104786,
  "client_secret_expires_at": 0,
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"
  ],
  "registration_client_uri": "https://server.example.com/via/v1/organizations/myorg/oauth/clients/2DxowL00RyG6OZdbYNaQs3R",
  "grant_types": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "response_types": [
    "code",
    "id_token"
  ],
  "client_name": "CUSTOMER_ORG_API_CLIENT",
  "scope": "myaspect.users myaspect.teams myaspect.teams.write",
  "x_api_key": "7FFAC9BB21628320FAEBC5786F152B0F2309D6528C7284B5E3E34E1AFE204A39",
  "client_description": "Fully-Authorized Client",
  "contacts": [
    "name1@company1.com",
    "name2@company2.com"
  ]
}

OAuthClientResponse

Properties

Name Type Required Restrictions Description
client_id string false none Client identifier, Server-generated identifier for the OAuth client. This cannot be changed.
client_secret string false none Client secret, will only be displayed once, and only upon client creation and new secret generation
client_id_issued_at number false none Time, in ticks, at which the client was issued. The
time is represented as the number of seconds from
1970-01-01T00:00:00Z as measured in UTC until the date/time of
issuance.
client_secret_expires_at number false none Time, in ticks, at which the client identifier will expire.
The time is represented as the number of seconds from
1970-01-01T00:00:00Z as measured in UTC until the date/time of
expiry.
0 means that it will never expire.
redirect_uris [string] false none Array of redirection URI strings for use in redirect-based flows such as the authorization code flow.
registration_client_uri string false none String containing the fully qualified URL of the client configuration endpoint for this client.
grant_types [string] false none Array of OAuth 2.0 grant type strings that the client can use at the token endpoint.
response_types [string] false none Array of the OAuth 2.0 response type strings that the client can use at the authorization endpoint.
client_name string false none Human-readable string name of the client
scope string false none String containing a space-separated list of OAuth 2.0 scope values
x_api_key string false none Alvaria™ generated x_api_key (x-api-key), used for API access tracking
client_description string false none Human Readable Description of a client.
contacts [string] false none Array of the OAuth 2.0 response type strings representing ways to contact people responsible for this client, typically email addresses.

ListOAuthClientResponseMinusSecret

[
  {
    "client_id": "2DxowL00RyG6OZdbYNaQs3R",
    "client_id_issued_at": 1659104786,
    "client_secret_expires_at": 0,
    "redirect_uris": [
      "https://client.example.org/callback",
      "https://client.example.org/callback2"
    ],
    "registration_client_uri": "https://server.example.com/via/v1/organizations/myorg/oauth/clients/2DxowL00RyG6OZdbYNaQs3R",
    "grant_types": [
      "authorization_code",
      "client_credentials",
      "refresh_token"
    ],
    "response_types": [
      "code",
      "id_token"
    ],
    "client_name": "CUSTOMER_ORG_API_CLIENT",
    "scope": "myaspect.users myaspect.teams myaspect.teams.write",
    "x_api_key": "7FFAC9BB21628320FAEBC5786F152B0F2309D6528C7284B5E3E34E1AFE204A39",
    "client_description": "Fully-Authorized Client",
    "contacts": [
      "name1@company1.com",
      "name2@company2.com"
    ]
  }
]

Properties

Name Type Required Restrictions Description
anonymous [OAuthClientResponseMinusSecret] false none [OAuth Client as defined here [https://datatracker.ietf.org/doc/html/rfc7591]]

OAuthClientResponseMinusSecret

{
  "client_id": "2DxowL00RyG6OZdbYNaQs3R",
  "client_id_issued_at": 1659104786,
  "client_secret_expires_at": 0,
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"
  ],
  "registration_client_uri": "https://server.example.com/via/v1/organizations/myorg/oauth/clients/2DxowL00RyG6OZdbYNaQs3R",
  "grant_types": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "response_types": [
    "code",
    "id_token"
  ],
  "client_name": "CUSTOMER_ORG_API_CLIENT",
  "scope": "myaspect.users myaspect.teams myaspect.teams.write",
  "x_api_key": "7FFAC9BB21628320FAEBC5786F152B0F2309D6528C7284B5E3E34E1AFE204A39",
  "client_description": "Fully-Authorized Client",
  "contacts": [
    "name1@company1.com",
    "name2@company2.com"
  ]
}

OAuthClientResponseMinusSecret

Properties

Name Type Required Restrictions Description
client_id string false none Client identifier, Server-generated identifier for the OAuth client. This cannot be changed.
client_id_issued_at number false none Time, in ticks, at which the client was issued. The
time is represented as the number of seconds from
1970-01-01T00:00:00Z as measured in UTC until the date/time of
issuance.
client_secret_expires_at number false none Time, in ticks, at which the client identifier will expire.
The time is represented as the number of seconds from
1970-01-01T00:00:00Z as measured in UTC until the date/time of
expiry.
0 means that it will never expire.
redirect_uris [string] false none Array of redirection URI strings for use in redirect-based flows such as the authorization code flow.
registration_client_uri string false none String containing the fully qualified URL of the client configuration endpoint for this client.
grant_types [string] false none Array of OAuth 2.0 grant type strings that the client can use at the token endpoint.
response_types [string] false none Array of the OAuth 2.0 response type strings that the client can use at the authorization endpoint.
client_name string false none Human-readable string name of the client
scope string false none String containing a space-separated list of OAuth 2.0 scope values
x_api_key string false none Alvaria™ generated x_api_key (x-api-key), used for API access tracking
client_description string false none Human Readable Description of a client.
contacts [string] false none Array of the OAuth 2.0 response type strings representing ways to contact people responsible for this client, typically email addresses.
Shell Node.js HTTP