Authentication

Before you can send requests to the OpenText Core Software Delivery Platform REST API, you must authenticate. The method you use depends on your use case.

In this topic:

Overview

Method	When to use	How it works
Sign in with an API access key or user credentials	Most integrations and automation. This is the recommended method.	Send a JSON body to sign_in. The server returns a session cookie that identifies all subsequent requests.
Interactive token sharing	Tools that cannot collect user credentials directly, such as IDE integrations authenticating through SSO or SaaS federation.	The tool requests an identifier, the user authenticates in a browser, and the tool retrieves the resulting session cookie.
Basic authentication	Quick tests and OData access. Not recommended for production automation.	Send an Authorization header with every request. No session is established. Disabled by default.

Sign in with an API access key or user credentials

To sign in, send a POST request to the sign_in resource, with a JSON body that contains your credentials.

POST /authentication/sign_in

You can authenticate in one of the following ways:

• API access key. Use a client ID and client secret. This is the recommended method for integrations and automation.

  {
      "client_id": "<your client ID>",
      "client_secret": "<your client secret>"
  }

• User credentials. Use a user name and password.

  {
      "user": "<your user name>",
      "password": "<your password>"
  }

When the request succeeds, the server returns a session cookie named LWSSO_COOKIE_KEY in the Set-Cookie response header. Store this cookie and send it with every subsequent request to identify your session.

Interactive token sharing

Interactive token sharing lets a tool obtain a session on behalf of a user who authenticates in a browser. This is useful for interactive tools, such as IDE integrations, when the user signs in through SSO or SaaS federation and the tool cannot collect the user's credentials directly.

The flow uses two REST calls with a browser authentication in between:

• Step 1. The tool requests an identifier and a browser sign-in URL.

• Step 2. The user opens the URL in a browser and signs in normally.

• Step 3. The tool polls OpenText Core Software Delivery Platform to retrieve the session token produced by the browser sign-in.

Step 1 – Generate an identifier

The tool sends a POST request, with the Content-Type header set to application/json, to the tokens resource:

POST /authentication/tokens

A successful call returns 200 with a unique identifier and the URL the user must open to authenticate:

{
    "id": "<identifier>",
    "authentication_url": "<url>"
}

Step 2 – Authenticate in a browser

The user opens the authentication_url from Step 1 in a browser and signs in as usual. After authenticating, the browser shows a message indicating that it can be closed. Behind this URL, the server uses the store_tool_token resource to associate the completed sign-in with the identifier from Step 1.

Step 3 – Retrieve the token

The tool retrieves the session token with a GET request. Use the id from Step 1, and for userName supply the same user name that was used to authenticate in the browser. For SSO, this is the user name sent in the assertion from the identity provider. Using the matching user name is essential to keep the flow secure.

GET /authentication/tokens/{id}?userName=<user name>

A successful call returns 200 with the token:

{
    "access_token": "<access token>",
    "id": "<id>",
    "cookie_name": "LWSSO_COOKIE_KEY"
}

Send the access_token value as the cookie named by cookie_name on every subsequent request, exactly as you would with a cookie obtained from sign_in.

The call returns 404 when the token cannot be produced, for any of the following reasons:

• The browser authentication from Step 2 has not completed yet. Poll again.

• The identifier is wrong or has expired.

• The userName does not match the user who authenticated in Step 2.

Note: The token is held only until it is retrieved. If it is not retrieved within a few minutes, the identifier and its token are discarded, and you must start again from Step 1.

Maintaining a session

The session cookie expires under two conditions: after a period of inactivity, known as the idle timeout, and after an absolute maximum age regardless of activity, known as the global timeout. When the session expires, requests are rejected and you must sign in again to obtain a new cookie. For long-running processes, sign in again whenever the session expires rather than signing in before every individual request.

You can keep a session alive across the idle timeout by resending the cookies you receive. Each response may include refreshed authentication cookies in its Set-Cookie headers; if you send those cookies back on your next request, the idle timeout is reset. A session can be extended this way only up to the global timeout. After the global timeout, the cookie expires, requests are rejected with 401, and you must sign in again.

Note: When you sign in with an API access key, the resulting session acts on behalf of the integration user that owns the key. When you sign in with user credentials, the session acts on behalf of that user.

Basic authentication

Where it is enabled, the API also accepts HTTP Basic authentication, in which credentials are sent in the Authorization header of each request instead of being exchanged for a session cookie. Because it authenticates on every call, Basic authentication is convenient for quick tests but less efficient than a shared session for repeated calls. To reduce that cost, the server caches a successful Basic authentication for 120 seconds by default. For automation, prefer signing in once and reusing the session cookie.

Basic authentication is disabled by default. To enable it, set the SUPPORTS_BASIC_AUTHENTICATION parameter. For details, see SUPPORTS_BASIC_AUTHENTICATION.

An administrator can set this parameter through the API as well as through the interface. A space administrator enables basic authentication on a single space:

PUT /api/shared_spaces/{space_id}/params/SUPPORTS_BASIC_AUTHENTICATION

{
    "value": "true"
}

Restricted access configuration

An administrator can restrict how the REST API is accessed. Access can be limited to API access keys only, rejecting user credentials, and the client types that may call the API can be constrained. If your requests are refused even with valid credentials, check these restrictions with your administrator.

When access is restricted to API access keys only, a direct REST request that is authenticated as a regular user is rejected. The OpenText Core Software Delivery Platform interface and standard clients, such as QoT, are exempt from this restriction and continue to allow user authentication.

These restrictions are controlled by the following parameters: RESTRICT_REST_API_TO_API_KEYS_ONLY limits access to API access keys, and CLIENT_TYPES_ALLOWED_TO_ACCESS_REST_API determines which client types remain exempt.

Sign out

To end a session, send a request to the sign_out resource. The response expires the authentication cookies. This resource works for every sign-in method.

POST /authentication/sign_out