Managing authentication for REST services

This REST API contains the information you need to sign in and create a session.

Get a list of URLs to use for authentication

Procedure

Construct the authorization API URL. You can construct this URL in one of two ways:
- By adding auth/discovery to the Rational® Test Control Panel base URL, as in the following example:
```
http://example.com:7819/RTCP/auth/discovery
```
- By using the REST API discovery URL to find that URL, as described in Discovering REST APIs.

Send an HTTP GET request to the authorization API URL. The URL returns a message in JSON format that specifies additional URLs, as in the following example:

{
  "subject": "http://example.com:7819/RTCP/auth",
  "links": [
    {
      "href": "http://example.com:7819/RTCP/auth/token",
      "rel": "http://jazz.net/auth/jsa/token"
    },
    {
      "href": "http://example.com:7819/RTCP/auth/introspection",
      "rel": "http://jazz.net/auth/jsa/introspection"
    },
    {
      "href": "http://example.com:7819/RTCP/auth/session-sign-in",
      "rel": "http://jazz.net/auth/jsa/session-signin"
    },
    {
      "href": "http://example.com:7819/RTCP/auth/session-sign-out",
      "rel": "http://jazz.net/auth/jsa/deauthorize"
    }
  ]
}

Sign in and create a session

Procedure

In the response from the authorization URL, locate the rel property with the following value:
```
http://jazz.net/auth/jsa/session-signin
```
See Get a list of URLs to use for authentication.
Send a POST request to the URL in the associated href property. That POST request uses HTTP Basic Authentication and specifies the username and password for the appropriate user account.
Using HTTP Basic Authentication involves setting the Authorization HTTP request header to the string "Basic" followed by a space, followed by a base64-encoded string that consists of the username, a colon, and the password. For example, for the username "user1" and the password "password", construct the string "user1:password". After base64 encoding, the string becomes "dXNlcjE6cGFzc3dvcmQ=". The following example shows the HTTP request:
```
POST /RTCP/auth/session-sign-in HTTP/1.1
Host: example.com:7819
Authorization: Basic dXNlcjE6cGFzc3dvcmQ=
Content-Length: 0
```
That request returns a response similar to the following example:
```
{ "token_type" : "urn:jazz:params:oauth:token-type:session",
  "access_token" : "552359hakks86205mqjdgy",
  "jazz_subject" : "user1"}
```
The jazz_subject property contains the username that you created a session for. The access_token property contains the security token for this session. For information about how to use this token to run REST API calls as this user, see REST and Domain level security.
In subsequent requests to other REST endpoints in the same domain, include that access token in the Authorization header and use the "X-Jazz-Session" as the authentication scheme identifier, as in the following example:
```
Authorization: X-Jazz-Session 552359hakks86205mqjdgy
```

Feedback