Bellus3D Face Cloud API

A REST API for client apps or web services to interface with Bellus3D Face Cloud

API Client

The client refers to an app (or a web service) that uses the API. To use the API, you need to get a Bellus3D developer account, and obtain client_id and client_secret for the app or the service from Bellus3D. If you have mulitple apps or services, you should obtain a client_id and client_secret for each of them.

API Acess Tokens

All API requests require an access token. You obtain an access token using Bellus3D OAuth2 Authentication. Once you have an access token, you add it to your API request headers to authenticate the client (your app) and the user making the requests. You need to add the word Bearer in front of the token. You should send the request via HTTPS.

  • Headers
  Authorization: `"Bearer " + access_token`
  (for example, `Bearer 72ab415822b56cf0f9f93f07fe978d9aae859325`)

For example, to get models of a user using curl:

curl -X GET "https://api_host/models" \
  -H "accept: application/json" \
  -H "Authorization: Bearer 82ab415822b56cf0f9f93f07fe978d9aae85932s"

Bellus3D OAuth2 Authentication

Bellus3D OAuth2 authentication supports two grant types to obtain access tokens:

  • client_credentials: For apps or web services that do not require Bellus3D user authentication (only require client_id and client_secret). Apps using the Bellus3D iOS SDK will use the client_id and client_secret that they receive from Bellus3D to activate the SDK.
  • password: For apps that require Bellus3D user authentication and can securly manage the user's signin credentials ( require client credentials plus username and password). Currently, only Bellus3D apps are allowed to use the password grant.

Client Credentials Grant

The client_credentials grant is for web services or client apps that want to manage their own users and simply want to use Bellus3D Face Cloud to upload, access or manage face models. Any face models uploaded using this type of access tokens will be owned by the client, not a user, and will not require user authentication.

Obtain an access token with the client_credentials grant

You should send a POST request with base64 encoded client credentials in request headers and the grant type in request body. You shoudl keep client_secret confidential and only send the request via HTTPS.

  • Headers
  Authorization: `"Basic " + client_id:client_secret base64'd`
  (for example, to use `application:secret`, you should send `Basic YXBwbGljYXRpb246c2VjcmV0`)
  Content-Type: `application/x-www-form-urlencoded`
  • Body
  `grant_type=client_credentials`

For example, using curl:

curl https://api_host/oauth/token \
  -d "grant_type=client_credentials" \
  -H "Authorization: Basic YXBwbGljYXRpb246c2VjcmV0" \
  -H "Content-Type: application/x-www-form-urlencoded"

Password Grant

The password grant should be used when user authentication is required. Any face model uploaded by a user will require user authentication to access and manage them.

Obtain an access token with the password grant

You need to include the client credentials in request headers, and the user credentials and grant type in request body:

  • Headers
  Authorization: `"Basic " + client_id:client_secret base64'd`
  (for example, to use `application:secret`, you should send `Basic YXBwbGljYXRpb246c2VjcmV0`)
  Content-Type: `application/x-www-form-urlencoded`
  • Body
  `grant_type=password&username=pedroetb&password=password`
  (contains 3 parameters: `grant_type`, `username` and `password`)

The body paramaters should be URL-encoded.

For example, using curl:

curl https://api_host/oauth/token \
  -d "grant_type=password" \
  -d "username=pedroetb" \
  -d "password=password" \
  -H "Authorization: Basic YXBwbGljYXRpb246c2VjcmV0" \
  -H "Content-Type: application/x-www-form-urlencoded"

Token Response

The token response body is a JSON message that contains the access token and the expiry time (in seconds.) The access tokens are usually short-lived (e.g. 2 hours.) You can use a long-lived (e.g. 2 weeks) refresh_token to extend their expiry time without asking the user to sign in again. Note that you may not get a refresh token with the client_credentials grant since you can simply request a new access token using client_id and client_secret.

{
  "access_token": "3e952f18916d3abd44b16005f81ca3ccb7eb33ea",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "cbef57f721ad0b5c3931624fc85d9a771b41bdcc"
}

Use refresh tokens to extend token expiry time

If an access token expires, you can use its refresh token to request a new access token with the refresh_token grant.

For example, using curl:

curl https://api_host/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=cbef57f721ad0b5c3931624fc85d9a771b41bdcc" \
  -H "Authorization: Basic YXBwbGljYXRpb246c2VjcmV0" \
  -H "Content-Type: application/x-www-form-urlencoded"

You will get a new access token, a refresh token, and a new token expiration time. You can repeat the process as long as the refresh token has not expired. A refresh token can only be used once to exchange for a new access token with the refresh_token grant.

Concurrent User Sessions

The API server has a limit on the number of concurrent sessions per user. Currently, each user is allowed to have up to two non-expiring access_tokens obtained with the password grant. Any additional access_tokens beyond the limit will be automatically invalidated when a new access_token is granted to a user. The limit does not apply to access_tokens obtained with the client_credential grant.

API Test Page

You can see the API documentation and test it at:

Api-docs

API Host

  • Prod Server: cloudapi.bellus3d.com
  • Dev Server (internal use only): b3dcloudapi-dev.azurewebsites.net