Jump to

• Request
• Response
• Examples

Request an access token

post

/rest/{version}/auth/token

Requests an access token by providing a valid credential string. The client creates the credential string by Base64-encoding username:password, where username is a user name the system recognizes, the colon is literal, and password is the current password associated with username. The client then supplies the encoded credentials in the Authorization header of the /rest/{version}/auth/token request, using the header value Basic <encoded credential string>.

Once the client has a valid token it must be supplied in the Authorization header of all subsequent requests, using the header value Bearer <token string>. Tokens have a limited lifetime of ten minutes, and the client must re-authenticate by issuing another /rest/{version}/auth/token request upon expiry of the current token.

A client may re-authenticate before its current token expires, if desired. This is useful if a client currently holds the configuration lock, and needs to keep ownership of the lock longer then the ten minutes an access token is valid, in order to complete lengthy configuration changes. In order to re-authenticate prior to the current access token expiring, the client must supply login credentials in the Authorization header, just like an initial access token request, but must also supply the current, unexpired access token in the body of the request, and set the Content-Type header to x-www-form-urlencoded.

While it exists, the configuration lock is tied to a token. If a REST client loses the token, the client will have to wait until the token expires before requesting the configuration lock.

Request

Path Parameters

• version:
  REST API version string.
  Available values: v1.2

Header Parameters

• Authorization:
  The value in the Authorization header must be the string "Basic {encoded credential string}", where {encoded credential string} is the Base64-encoding of "username:password".
• Content-Type(optional):
  If the client is requesting a new access token prior to the expiration of its current, unexpired token, the current, unexpired token must be provided in the request body and the Content-Type header must be set to the value x-www-form-urlencoded.

Back to Top

Response

200 Response

The authentication credentials are valid and an access token is returned to the client. The token must be used in the Authorization header of all subsequent REST requests.

400 Response

The Authorization header is missing, is malformed, or does not contain a value that can be decoded into a username and password.

401 Response

Unauthorized - Request lacks valid authentication credentials.

404 Response

Unsupported versionId in URI.

Back to Top

Examples

Example of Accessing the API with cURL

The following example shows how to request an access token by submitting a POST request on the REST resource using cURL. For more information about cURL, see Use cURL.

curl -X POST \
    --header "Accept: application/xml" \
    --user admin:password \
    "https://${SBCIP}/rest/v1.1/auth/token"

Example of Accessing the API with Python

The following example shows how to request an access token by submitting a POST request on the REST resource using Python.

import requests
import base64
encoded_bytes = base64.encodestring(b"admin:<password>").strip()
encoded_str = encoded_bytes.decode('utf8')
auth_header = { "Authorization": "Basic " + encoded_str }
url  = "https://" + sbcip + "/rest/v1.1/auth/token"
resp = requests.post(url, headers=auth_header)

Example of the Response Headers

The following shows an example of the response headers.

HTTP/1.1 401
Server: nginx/1.14.1
Date: Wed, 01 Apr 2020 13:35:08 GMT
Content-Type: application/xml
Transfer-Encoding: chunked
Connection: keep-alive

Example of the Response Body

The following example shows the contents of the response body in XML format.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
  <data>
    <accessToken>YWRtaW4 ... YThmM2U=</accessToken>
  </data>
  <messages/>
  <links/>
</response>

Back to Top