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
Once the client has a valid token it must be supplied in the Authorization header of all subsequent requests, using the header value
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
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.
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(required):
REST API version string.
Available values: v1.2
Header Parameters
-
Authorization(required):
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:
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.
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.
Examples
Examples of Accessing the API
The following example shows how to request an access token using curl.
curl -X POST \
--header "Accept: application/xml" \
--user admin:password \
"https://${SBCIP}/rest/v1.1/auth/token"The following example shows how to request an access token using Python.
import requests
import base64
from lxml import etree
encoded_str = base64.encodestring("admin:<password>").strip()
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 Body
The following example shows the contents of the response body in XML.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
<data>
<accessToken>YWRtaW4 ... YThmM2U=</accessToken>
</data>
<messages/>
<links/>
</response>