Vuforia Web API Authentication¶

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

Authentication Methods¶

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
Cloud Targets Web API Cloud Query Web API VuMark Generation Web API	Model Target Web API Cloud Area Targets Web API Area Target Capture API Login credentials for the Area Target Generator and Model Target Generator.

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 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.

Credentials scopes¶

The following scopes are available:

Scope Name	Scope Definition	Permissions
OAuth2 Client Credentials	oauth2.clientcredentials.all	Full access to management of client credentials

Model Targets scopes¶

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

Area Targets scopes¶

OAuth2 Client credentials with correct scopes are required for the python client to communicate with the Vuforia Cloud to create Cloud Area Targets.

The following scopes are available:

Scope Name	Scope Definition	Permissions
Area Targets - ALl	areatargets.all	Full access to Cloud Area Target APIs
--	areatargets.create	Create Area Targets.
--	areatargets.delete	Delete Area Targets.
--	areatargets.read	Read access for authoring Area Target assets and read-only operations, i.e., list and get status.
--	areatargets.delivery	Read access on Area Target delivered assets at runtime.

Other scopes¶

The following scopers are available:

Scope Name	Scope Definition	Permissions
Create Dataset Signature	datasetsignature.create	Create dataset signature (to be used in SDK Area Target Capture API or as an alternative to login to the ATG and MTG) NOTE: The MTG also requires the modeltargets.all scope to generate Model Targets.

Manage your OAuth2 Client Credentials¶

Client credentials can be created, updated, listed, and deleted using the Credentials tab on the Vuforia Engine Developer Portal or via a REST API. See the Credentials tab 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 can be used:

To authenticate Cloud Area Targets Web API.
- To authenticate generation and management of Cloud Area Targets Targets.
- To authenticate streaming Cloud Area Targets from Engine SDK. See unity and native for streaming Cloud Area Targets.
To Authenticate Area Target Capture 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 Model Target Web API.
- To authenticate the generation of Model Targets, execute a login request via the client_credentials to obtain a JWT token.
As login credentials in the Area Target Generator.
As login credentials in the Model Target Generator.

See Engine Developer Portal Credentials for creating and managing client credentials on the Engine Developer Portal.

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¶

To generate client credentials via curl, you need to:

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"

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"

Copy the returned (client_id, client_secret) to a safe location.

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"
  }
}

Learn More¶

Area Target Capture API

Model Target Web API

Cloud Area Target Web API

Vuforia Web Services API

Cloud Targets Web API

Engine Developer Portal Credentials

Vuforia Web API Authentication¶

Authentication Methods¶

VWS Authentication¶

Client and Server Access keys¶

Signature¶

OAuth2 Authentication¶

Obtain a JWT Token via password grant¶

Obtain a JWT Token via client_credentials grant¶

OAuth2 Scopes¶

Credentials scopes¶

Model Targets scopes¶

Area Targets scopes¶

Other scopes¶

Manage your OAuth2 Client Credentials¶

Create Client Credentials via REST API¶

Example curl commands to create client credentials¶

List client credentials¶

Update client credentials¶

Delete client credentials¶

Errors¶

Learn More¶

Obtain a JWT Token via `password` grant¶

Obtain a JWT Token via `client_credentials` grant¶