Authentication

The Commander API supports Basic authentication and JSON Web Token (JWT) authentication.

Basic authentication

Basic authentication is a standard authentication mechanism that's built into the HTTP protocol. To use this mechanism, supply your Base64-encoded credentials with each API call. This mechanism is best suited for scenarios that involve a low volume of API calls. For instance, it's a convenient way to authenticate when trying out endpoints using curl or Postman.

In addition to trying out endpoints, Basic authentication can be used to develop integrations. However, it's not recommended for scenarios that require frequent API calls that occur in quick succession. For those scenarios, the more efficient JWT authentication mechanism is recommended.

Authenticating as an admin user using Basic authentication

In this scenario, you authenticate as an admin user using Basic authentication. The user account is "superuser" and the password is "mySecret". As per the HTTP Basic authentication protocol, the username and password fields are delimited by a colon and Base64-encoded.

To authenticate as this admin user using Basic authentication:

  1. Calculate the Base64 encoding of the credentials. For example, superuser:mySecret is encoded as c3VwZXJ1c2VyOm15U2VjcmV0.
  2. Construct the Authorization header using the keyword Basic and reference the credentials.
    Authorization: Basic c3VwZXJ1c2VyOm15U2VjcmV0
  3. Supply the Authorization header with each request.

Authenticating as a portal user using Basic authentication

In this scenario, you authenticate as a portal user who is a member of an organization using Basic authentication. The user account "jsmith" is a member of the "org1" organization, and has a password of "mySecret". Because the user is a member of an organization, the Basic authentication username field contains both the account and the organization, delimited by a semi-colon. For example, jsmith;org1. As per the HTTP Basic authentication protocol, the username and password fields are delimited by a colon and Base64-encoded.

To authenticate as this portal user using Basic authentication:

  1. Calculate the Base64 encoding of the credentials. For example, jsmith;org1:mySecret is encoded as anNtaXRoO29yZzE6bXlTZWNyZXQ=.
  2. Construct the Authorization header using the keyword Basic and reference the Base64-encoded credentials.
    Authorization: Basic anNtaXRoO29yZzE6bXlTZWNyZXQ=
  3. Supply the Authorization header with each request.

JWT authentication

JSON Web Token Authentication is a stateless authentication mechanism. To use this method, you must request a token using your credentials. The token contains all the data needed by the Commander API to authorize the API call without additional processing. This allows the API to respond more quickly and efficiently than with Basic authentication.

The token contains two expiration times: access expiration and renewal expiration. When the access expiration is reached, the token must be renewed. When the renewal expiration is reached, the user must re-authenticate and get a new token.

You must refresh your token every minute to avoid access expiration. If you don't refresh the token once per minute, you'll receive an error and will need to refresh the token before performing additional API calls. If the token isn't refreshed for 15 minutes, then renewal expiration occurs. At this point the token is non-refreshable and you'll need to authenticate again and receive a new token.

The workflow is as follows:

JWT Authentication Workflow

Authenticating as an admin user using JWT authentication

In this scenario, you authenticate as an admin user using JWT authentication. The user account is "superuser" and the password is "mySecret". Because the admin user isn't authenticating as a member of an organization, the optional organization property is omitted from the request.

To authenticate as this admin user using JWT authentication:

  1. Submit a token create request by supplying the credentials to endpoint POST https://vCommander.embotics.com/rest/v3/tokens.
    {
    	"username": "superuser",
    	"password": "mySecret"
    }			
  2. Upon a 201 success response, obtain the token from the response body.
    {
    	"token": "eyJhbGciOiJSUzI1NiJ9...JjpS5bmp8OtpJe5T92vQ9TSIjMQ"
    }			
  3. Construct the Authorization header using the keyword Bearer and reference the token.
    Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...JjpS5bmp8OtpJe5T92vQ9TSIjMQ
  4. Supply the Authorization header with each request.

Authenticating as a portal user using JWT authentication

In this scenario, you authenticate as a portal user using JWT authentication. The user account "jsmith" is a member of the "org1" organization, and has a password of "mySecret".

To authenticate as this portal user using JWT authentication:

  1. Submit a token create request by supplying the credentials to endpoint POST https://vCommander.embotics.com/rest/v3/tokens.
    {
    	"username":"jsmith",
    	"password":"mySecret",
    	"organization:"org1"
    }		
  2. Upon a 201 success response, obtain the token from the response body.
    {
    	"token": "eyJhbGciOiJSUzI1NiJ9...6eMX8HVvpH37Yz9D4KRoMGUAPO88A"
    }
  3. Construct the Authorization header using the keyword Bearer and reference the token.
    Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...6eMX8HVvpH37Yz9D4KRoMGUAPO88A
  4. Supply the Authorization header with each request.