Vuforia Web API Authentication

Use the OAuth2 or Vuforia Web Services (VWS) scheme to authenticate requests with the Vuforia Web API.

Supported Features

Various Vuforia features and services are available through a Web API. Use the authentication method supported by the specific features as described in the table below.

VWS Authentication OAuth2 Authentication

VWS Authentication

VWS Authentication is a custom authentication scheme loosely based on the OAuth 1.0a specification. It requires a key pair that is available for each a Cloud or VuMark Database in the Target Manager.

Requests to the Web APIs that support the VWS Authentication must include the HTTP Authorization header as follows:

Authorization: VWS {access_key}:{signature}

The access_key is either the server_access_key or client_access_key while the signature is computed from either the server_secret_key or client_secret_key.

Client and Server Access keys 

Each Cloud or VuMark Database has two set of key pairs – the Server Access Key Pair and the Client Access Key Pair.

  • The Server Access Key Pair (server_access_key, server_secret_key) allow uploading and managing targets via the Cloud Targets Web API. The Server Access Key Pair has read and write permissions on the database.
  • The Client Access Key Pair (client_access_key, client_secret_key) allow an app to query the database for image recognition services. The Client Access Keys have read-only access to the database. When using the Vuforia Engine SDK to access Cloud Recognition, the Client Access Key pair needs to be embedded in the application and passed to Vuforia Engine during initialization of the CloudRecoBehaviour for Unity and VuCloudImageTargetConfig for Native. See Cloud Recognition for more details.

Signature

The Signature in a VWS authentication header is a string computed as follows:

Signature = Base64(HMAC-SHA1(server_secret_key, StringToSign));
StringToSign = HTTP-Verb + "\n" + 
               Content-MD5 + "\n" + 
               Content-Type + "\n" + 
               Date + "\n" + 
               Request-Path;

Where:

  • HTTP-Verb: is the HTTP method used for the action, for example, GET, POST, and so forth.
  • Content-MD5: is the hexadecimal MD5 hash of the whole request body (from the first boundary to the last one, including the boundary itself). For request types without request body, include the MD5 hash of an empty string which is “d41d8cd98f00b204e9800998ecf8427e".
  • Content-Type: is the content-type of the request body (like multipart/form-data). Use an empty string for request types without a request body.
  • Date: is the current date per RFC 2616, section 3.3.1, rfc1123-date format, for example, Sun, 22 Apr 2012 08:49:37 GMT. The same Date must also be supplied in the HTTP Date header.

    NOTE: The date and time always refer to GMT

  • Request-Path: The path in the URL after the domain is the request-path.  That is, a request to https://vws.vuforia.com/targets/{target_id} has request-path equal to /targets/{target_id}.

OAuth2 Authentication

OAuth2 is an industry-standard authentication mechanism.  The Vuforia Web Services API support a 2-legged OAuth2 flow with password and client_credentials grant types.

The credentials are used to obtain a JWT token according to the grant type:

  • The password grant uses the email and password of a Vuforia Developer Portal account. This grant gives access to the full set of scopes (permissions) available for a user, and therefore, it is recommended to be used only for management of client credentials and not for embedding in mobile applications or backends.
  • The client_credentials grant uses a (client_id, client_secret) credential pair and can be restricted to a set of user-defined scopes (permissions). Client credentials are suitable for use cases where it is required to restrict access to a subset of scopes or to have the ability to revoke access, e.g., for in-app embedding.

In a 2-legged OAuth2 flow, the set of credentials is exchanged for a JWT token that is then used in the HTTP Authorization header to authenticate API calls:

Authorization: Bearer {JWT Token}

Obtain a JWT Token via password grant

Execute a POST request to https://vws.vuforia.com/oauth2/token to exchange Engine Vuforia Developer Portal credentials for a JWT token.

The request must have content-type application/x-www-form-urlencoded with the following fields:

Field name

Type

Mandatory

Description

grant_type

String

Yes

Must be set to the value password.

username

String

Yes

The email registered on the Vuforia Developer Portal.

password

String

Yes

The password for Vuforia Developer Portal account.

scope

String

No

List of scopes separated by spaces.

If no scopes are provided, the returned token contains all the scopes available for user.

A successful response will contain the JWT token and its expiration:

{
    "access_token": "{JWT_TOKEN}",
    "token_type": "bearer",
    "expires_in": 3600
}

Obtain a JWT Token via client_credentials grant

Execute a POST request to https://vws.vuforia.com/oauth2/token to exchange client credentials for a JWT token.

The client_credentials must be sent in the HTTP Authorization header using HTTP basic access authentication, that is:

Authorization: Basic base64("{client_id}:{client_secret}")

The body of the request must have content-type application/x-www-form-urlencoded with the following data:

Field Name

Type

Mandatory

Description

grant_type

String

Yes

Must be set to the value client_credentials.

scope

String

No

List of scopes separated by spaces.

If no scopes are provided, the returned token contains all the scopes currently associated to the client_credentials provided in the Authorization header.

Example login request:

curl –XPOST --user "<client_id>:<client_secret>" "https://vws.vuforia.com/oauth2/token"

A successful response will contain the JWT token and its expiration:

{
    "access_token": "{JWT_TOKEN}",
    "token_type": "bearer",
    "expires_in": 3600
}

 

OAuth2 Scopes

Scopes are an OAuth2 mechanism to limit the permissions associated to JWT tokens generated via the password grant or client_credentials grant.

Scopes can and should be specified when creating a new (client_id, client_secret) key pair to be inherited by the JWT tokens that are obtained when authenticating with such key pair.

The following scopes are available:

Scope Name

Scope Definition

Permissions

Model Targets - All

modeltargets.all

Full access to Model Target APIs

Model Targets

modeltargets.standardmodeltarget.all

Full access to standard Model Target APIs

Advanced Model Targets

modeltargets.advancedmodeltarget.all

Full access to advanced Model Target APIs

OAuth2 Client Credentials

oauth2.clientcredentials.all

Full access to management of client credentials

Create Dataset Signature

datasetsignature.create

Create dataset signature (to be used in SDK Area Target Capture API)

Manage your OAuth2 Client Credentials

Client credentials can be created, updated, listed, and deleted using the Credentials Manager on the Vuforia Engine Developer Portal or via a REST API. See the Credentials Manager section for an explanation of the user interface.

Client credentials consist of a client_id and client_secret key pair and associated scopes and are typically used in applications and backends to be exchanged for a JWT Token. You can create a maximum of 100 Client Credentials per account.

The client credentials are used by the SDK Area Target Capture API and the Model Target Web API.

  • To authenticate the generation of Area Targets, insert the key pair in the AreaTargetCaptureBehaviour’s Client ID and Client Secret for Unity or the VuAreaTargetCaptureGenerationConfig.userAuth and .secretAuth for native
  • To authenticate the generation of Model Targets, execute a login request via the client_credentials to obtain a JWT token.

Credentials Manager interface

Log in on the Developer Portal and use the Credentials manager to view, create, update, and delete your OAuth2 Client Credentials.

The main page lists client credentials associated with your Vuforia Developer Account.

  1. To create new Client Credentials, click Create new credentials.

  2. Give your credential pair a unique and descriptive name and assign the scopes. See OAuth2 Scopes for details on the available scopes. The credential name will not be the same as the Client ID.
  3. Click Create. Then Download or Copy the Client ID and Client Secret. The Secret will not be shown again!

Once created, you can make further edits to manage the scopes associated to Client Credentials from the list. This allows adding and revoking permissions to existing applications that are using the credentials.

To delete a credential, Click the bin icon. Type Yes to confirm deletion. This action cannot be undone.

Create Client Credentials via REST API

API requests to manage client credentials need to be authenticated via a JWT Token. See the curl example below for a typical interaction with the API.

The POST /oauth2/clientcredentials API allows creation of new Client Credentials with selected scope definitions.

Request Method: POST

Request URL: https://vws.vuforia.com/oauth2/clientcredentials

The body of the request must have content-type application/json with the following data:

Field Name

Type

Mandatory

Description

scopes

Array[String]

Yes

An array of scopes to be associated with the created client credentials.

Example request:

POST /oauth2/clientcredentials HTTP/1.1
Host: vws.vuforia.com
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json
{
  "scopes": [
    "modeltargets.standardmodeltarget.all",
    "modeltargets.advancedmodeltarget.all"
  ]
}

Example response:

201 Created
{
  "clientId": "8YUK8NT1UCWR6PBUAHAWV",
  "clientSecret": "f4k3JuuhS8pkleLhqyh3JnDqZzKQPf4k3"
}

NOTE: clientSecret must be noted down and stored safely as it cannot be retrieved later.

Example curl commands to create client credentials

In order to generate client credentials via curl, you need to:

  1. Exchange the Vuforia Developer Portal username and password for a JWT token.
    curl -X POST https://vws.vuforia.com/oauth2/token \ 
      -H 'Content-Type: application/x-www-form-urlencoded' \ 
      --data-urlencode "grant_type=password" \ 
      --data-urlencode "username=$email" \ 
      --data-urlencode "password=$password"
  2. Copy the generated access_token into the authorization header of the POST request below. Adapt the scopes to your needs.
    curl -X POST https://vws.vuforia.com/oauth2/clientcredentials \
      -H "Authorization: Bearer $access_token" \ 
      -d '{"scopes": ["datasetsignature.create"]}' \ 
      -H "Content-Type: application/json"
  3. Copy the returned (client_idclient_secret) to a safe location.

Example execution:

List client credentials

You can retrieve the list of your client credentials. The operation will list client IDs and their scopes.

Request Method: GET

Request URL: https://vws.vuforia.com/oauth2/clientcredentials

Example Request

GET /oauth2/clientcredentials HTTP/1.1
Host: vws.vuforia.com
Authorization: Bearer {JWT_TOKEN}

Example Response

200 OK
[
    {
        "clientId": "8YUK8NT1UCWR6PBUAHAWV",
        "scopes": [
            "modeltargets.standardmodeltarget.all",
            "modeltargets.advancedmodeltarget.all"
        ]
    }
]

Update client credentials

Change the scopes associated to your client_credentials.

Request Method: PUT

Request URL: https://vws.vuforia.com/oauth2/clientcredentials/{clientId}/scopes

Example Request

PUT /oauth2/clientcredentials/8YUK8NT1UCWR6PBUAHAWV/scopes HTTP/1.1
Host: vws.vuforia.com
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json
{
  "scopes": [
    "modeltargets.standardmodeltarget.all"
  ]
}

Example Response

200 OK
[
    {
        "clientId": "8YUK8NT1UCWR6PBUAHAWV",
        "scopes": [
            "modeltargets.standardmodeltarget.all",
        ]
    }
]

 

Delete client credentials

Delete existing client credentials with the clientId.

Request Method: DELETE

Request URL: https://vws.vuforia.com/oauth2/clientcredentials/{clientId}

Example Request

DELETE /oauth2/clientcredentials/8YUK8NT1UCWR6PBUAHAWV HTTP/1.1
Host: vws.vuforia.com
Authorization: Bearer {JWT_TOKEN}

Example Response

204 No Content

Errors

The client credentials management API returns errors in a format compliant with the Microsoft REST API guidelines.

Example error response:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "clientcredential with ID={YourClientID} not found",
    "target": "clientcredential"
  }
}