Authentication

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

Basic authentication

Basic authentication is a standard authentication method that is built into the HTTP protocol. To use this method, supply your Base64-encoded credentials with each REST call. This method is best suited for scenarios that involve a low volume of REST calls. For instance, it is 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 is not recommended for scenarios that require frequent REST calls made in quick succession. For those scenarios, the more efficient JWT authentication method is recommended.

Authenticate as an Admin Portal 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.

  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.

Authenticate as a Service 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.

  1. Calculate the Base64 encoding of the credentials.

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

JSON Web Token authentication

JSON Web Token authentication is a stateless authentication method. The JSON web token (JWT) contains all the data needed for the Commander API to authorize REST requests without additional processing. This allows the API to respond more quickly and efficiently than with basic authentication.

Commander supports two forms of JWT authentication:

  • A bearer authentication scheme available to Admin and Service Portal users
  • A bearer cookie authentication scheme available to Admin Portal users only

JWT bearer authentication

In the JWT bearer authentication scheme, users create a JSON web token from their credentials using the endpoint /tokens. To authorize future REST calls, this token must be passed in the authorization header of future REST request using the following format: 

Authorization: Bearer {token}

The token has two expiration times: access expiration and renewal expiration.

  • When the access expiration is reached, the token must be renewed with a POST request to the endpoint /tokens/refresh before you can make additional REST calls. You must refresh your token every minute to avoid access expiration.
  • After 15 minutes without a refreshed token, the renewal expiration is reached, at which point you must create a new token.

The workflow is as follows:

JWT Bearer Authentication flowchart

Authenticate as an Admin Portal user using JWT bearer authentication

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

  1. Submit a token create request by supplying the credentials to the 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.

Authenticate as a Service Portal user using JWT bearer authentication

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

  1. Submit a request to create a JSON web token by supplying user credentials to the 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.

If the access expiry for the JSON token has passed, the token must be refreshed before making additional API calls. If the renewal expiry for the JSON token has passed, a new token must be created.

JWT bearer cookie authentication

The JWT bearer cookie authentication scheme is a more secure form of JWT authentication. A cookie containing a JSON web token is created with a POST request to the endpoint /token-cookie, and stored in your web browser to be passed automatically on future REST requests. To perform future REST requests, construct the Authorization header using the following format:

Authorization: BearerCookie

The JSON web token has two expiration times: access expiration and renewal expiration.

  • When the access expiration is reached, the token must be renewed with a POST request to the endpoint /token-cookie/refresh before you can make additional REST calls. You must refresh your token every minute to avoid access expiration.
  • After 15 minutes without a refreshed token, the renewal expiration is reached, at which point you must create a new token.

The workflow is as follows:

JWT BearerCookie Authentication flowchart

Authenticate as an Admin Portal user using JWT bearer cookie authentication

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

  1. Submit a request to create a token cookie and JSON web token by supplying user credentials to the endpoint POST https://vCommander.embotics.com/rest/v3/tokens-cookie. 
    {
	"username": "superuser",
	"password": "mySecret"
}
  2. Upon a 201 success response, the token cookie containing the JWT will be stored in your browser and passed automatically for authentication on future REST requests.
  3. Construct the Authorization header using the keyword BearerCookie. 
    Authorization: BearerCookie

4. Supply the Authorization header with each request.