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 |
|
|
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 theCloudRecoBehaviourfor Unity andVuCloudImageTargetConfigfor 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
passwordgrant 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_credentialsgrant 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 |
| 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 |
| 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 |
Example login request:
1
Copy
curl –XPOST --user "
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:
- 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" - Copy the generated
access_tokeninto 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" - 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" } }