Authentication

note

The following instructions assume:

• You created a free developer account.
• You created credentials in the Vertex Console and have your Vertex client ID and secret.

The Vertex Platform uses OAuth 2.0 for authenticating and authorizing access to its APIs. This guide explains how authentication works, the different OAuth2 grant types supported, and best practices for securely integrating your application.

OAuth2 Overview

Authentication in the Vertex Platform is based on the OAuth 2.0 framework. Every application that needs to access the Platform APIs must first register as an Application.

Applications

An Application represents a client integrating with the Vertex Platform. It includes:

• A Client ID: A public identifier for your application
• A Client Secret: A private credential used to authenticate your application
• An associated Account: The Platform account that owns the application

Applications can request access tokens by using one of several OAuth2 grant types, depending on the use case and deployment model.

Supported Grant Types

The Platform supports a handful of grant types that support different authentication scenarios.

Client Credentials

Use this flow when your application needs to authenticate as itself, without acting on behalf of a user.

• Use case: Server-to-server API calls.
• Token scope: Access to resources owned by the application's account.

Request

curl --location --request POST \
  --url "https://platform.vertexvis.com/oauth2/token" \
  --header "Authorization: Basic $(echo -n "[YOUR_CLIENT_ID]:[YOUR_CLIENT_SECRET]" | base64)" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials"

Response

{
  "access_token": "[YOUR_ACCESS_TOKEN]",
  "account_id": "[YOUR_ACCOUNT_ID]",
  "expires_in": 3600,
  "scopes": [],
  "token_type": "bearer"
}

Authorization Code

Use this flow when your application needs to authenticate a user and obtain permission to act on their behalf.

• Use case: Web applications with user login flows.
• Token scope: User-level access to resources.

This flow requires a redirect URI and an interactive login experience. After authorization, the server issues an authorization code, which can be exchanged for an access token.

note

If your application already authenticates users via an OIDC-compliant identity provider (such as Okta, Azure AD, or Auth0), consider using the Token Exchange flow instead. This allows you to reuse your existing user session and avoid a second login prompt.

Refresh Token

Use this flow to obtain a new access token after the previous one has expired, without prompting the user to log in again.

• Use case: Long-lived user sessions.
• Precondition: The original token was obtained using the authorization code flow.

Token Exchange (RFC8693)

Use this flow to exchange a token issued by an external identity provider (IdP) for a Vertex Platform token.

• Use case: Customers using their own IdP (e.g., Okta, Azure AD) to authenticate users and integrate with Vertex user-level APIs (e.g. Vertex Collaboration APIs).
• Token scope: User-level access to resources.

To enable token exchange, your deployment must be configured with the OidcUserinfoEndpoint Cloudformation parameter pointing to your IdP’s userinfo endpoint.

Request

curl --location --request POST 'https://platform.vertexvis.com/token/exchange' \
  --header "Authorization: Basic $(echo -n "[YOUR_CLIENT_ID]:[YOUR_CLIENT_SECRET]" | base64)"
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' \
  --data-urlencode 'subject_token=<EXTERNAL_IDP_TOKEN>'

Response

{
  "access_token": "[YOUR_ACCESS_TOKEN]",
  "account_id": "[YOUR_ACCOUNT_ID]",
  "expires_in": 3600,
  "scopes": [],
  "token_type": "bearer"
}

When a token exchange request is performed:

1. The Vertex Platform calls your configured OidcUserinfoEndpoint using the provided subject_token.
2. It extracts the user's identifier from the sub field of the response.
3. That identifier must match a User in the Vertex Platform with a corresponding idpId.

important

The idpId of the Vertex User must exactly match the user ID returned by your identity provider. This is how the Platform links external users to internal user records.

For example, if your IdP returns:

{
  "sub": "00u123example",
  "name": "Jane Doe",
  "email": "jane.doe@example.com"
}

Then the user in the Vertex Platform must be created with:

{
  "idpId": "00u123example",
  "name": "Jane Doe",
  "email": "jane.doe@example.com"
}

Supported Token Types

Token Type	Token Type Identifier	Support
JWT	urn:ietf:params:oauth:token-type:jwt	❌
Access Token	urn:ietf:params:oauth:token-type:access_token	✅
Refresh Token	urn:ietf:params:oauth:token-type:refresh_token	❌
ID Token	urn:ietf:params:oauth:token-type:id_token	❌
SAML 1.1 Assertion	urn:ietf:params:oauth:token-type:saml1	❌
SAML 2.0 Assertion	urn:ietf:params:oauth:token-type:saml2	❌

OAuth2 Best Practices

Here are some key security and implementation best practices to follow when integrating with the Vertex Platform:

• Never expose a client secret in frontend applications. Client secrets should only be used in secure, backend environments.
• Use the appropriate grant type for your application model.
  • Use client credentials for backend automation.
  • Use authorization code for user-authenticated flows.
  • Use token exchange if users authenticate via an external IdP.
• Secure redirect URIs. Register only trusted and validated redirect URIs for authorization code flows.
• Scope tokens minimally. Request only the permissions your application needs.
• Implement token expiration handling. Handle 401 Unauthorized responses by refreshing tokens or re-initiating the flow.
• Store refresh tokens securely. Treat them like credentials; store only in secure, server-side environments.

Stream Keys

In addition to OAuth2 access tokens, the Vertex Platform supports Stream Keys for authenticating access to view Scenes in the Viewer component.

Stream Keys are scoped to individual Scenes and are intended to be used client-side (e.g., in the browser) for securely loading visual content without requiring a user login or OAuth2 flow.

Creating a Stream Key

To create a Stream Key, make a POST request to the following endpoint using an OAuth2 access token:

Request

curl --location --request POST \
  --url "https://platform.vertexvis.com/scenes/[YOUR_SCENE_ID]/stream-keys" \
  --header "Authorization: Bearer [YOUR_ACCESS_TOKEN]" \
  --header "Content-Type: application/vnd.api+json" \
  --data '{
  "data": {
    "attributes": {
      "expiry": 600
    },
    "type": "stream-key"
  }
}'

Response

{
  "data": {
    "attributes": {
      "key": "[YOUR_STREAM_KEY]",
      "expiry": 600
    },
    "id": "[YOUR_STREAM_KEY_ID]",
    "relationships": {
      "scene": {
        "data": {
          "id": "[YOUR_SCENE_ID]",
          "type": "scene"
        }
      }
    },
    "type": "stream-key"
  }
}

Using the Stream Key

Pass the returned key to the Viewer component’s load method:

async function main() {
  const viewer = document.querySelector('vertex-viewer');
  await viewer.load('urn:vertex:stream-key:[YOUR_STREAM_KEY]');
}

Notes

• The expiry field defines how long the stream key is valid (in seconds).
• Stream Keys are short-lived and intended for temporary access.
• You must use an OAuth2 access token to create a stream key.