1. REST API for Session Border Controller Release 8.2
  2. Tasks
  3. auth

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, password is the current password associated with username, and the colon is literal. The client then supplies the encoded credentials in the Authorization header of the /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 /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.

Request

Path Parameters
Header Parameters
  • 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".
  • 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.

There's no request body for this operation.

Back to Top

Response

Supported Media Types

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.
Body ()
Root Schema : response
Type: object
Show Source
Nested Schema : data
Type: object
Show Source
Nested Schema : messages
Type: object

400 Response

The Authorization header is missing or malformed. For example, the header may contain a value that cannot be decoded into a username and password.
Body ()
Root Schema : response
Type: object
Show Source
Nested Schema : data
Type: object
Nested Schema : messages
Type: object
Show Source

403 Response

Invalid credentials.
Body ()
Root Schema : response
Type: object
Show Source
Nested Schema : data
Type: object
Nested Schema : messages
Type: object
Show Source

404 Response

Unsupported versionId in URI.
Body ()
Root Schema : response
Type: object
Show Source
Nested Schema : data
Type: object
Nested Schema : messages
Type: object
Show Source
Back to Top

Examples

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 <username>:<password> \
    'https://10.0.0.2/rest/v1.0/auth/token'

Example of the Response Headers

The following shows an example of the response headers.

HTTP/1.1 200 OK
Date: Tue, 07 Aug 2018 21:00:26 GMT
Cache-Control: no-cache
Content-Length: 352
Content-Type: application/xml
Connection: keep-alive
Keep-Alive: timeout=60, max=99
Last-Modified: Tue, 07 Aug 2018 21:00:26 GMT
X-Appweb-Seq: 75

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>YWRtaW4sYWRtaW4sMjAxOC . . . 0wOC0wNyAyME5YzY=</accessToken>
  </data>
  <messages/>
  <links/>
</response>
Back to Top