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

1

Copy

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:

123456

Copy

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:

1

Copy

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:

12345

Copy

{ "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:

1

Copy

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:

1

Copy

curl –XPOST --user ":" "https://vws.vuforia.com/oauth2/token"

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

12345

Copy

{ "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 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 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 can be used:

• 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 Vuforia Credentials Manager 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:

12345678910

Copy

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:

12345

Copy

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:

1. Exchange the Vuforia Developer Portal username and password for a JWT token.

   12345

   Copy

   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.

   1234

   Copy

   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_id, client_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

123

Copy

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

Example Response

12345678910

Copy

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

123456789

Copy

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

123456789

Copy

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

123

Copy

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

Example Response

1

Copy

204 No Content

Errors

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

Example error response:

1234567

Copy

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