Skip to main content

Authentication

Overview​

The AdminAPI REST services use JWT-based bearer tokens for authentication.

Before accessing protected endpoints, clients must authenticate with PubServer, obtain a session ID, and exchange that session ID for an AdminAPI token. The token can then be supplied either in the Authorization header as a Bearer token or in the adminToken cookie.

Authentication Flow​

Authentication consists of the following steps:

  1. Authenticate with PubServer and obtain a session ID.
  2. Exchange the session ID for an AdminAPI token.
  3. Include the token in subsequent AdminAPI requests.

Step 1: Request a PubServer Session ID​

The PubServer AuthService provides an endpoint for creating a user session.

Request​

  • Endpoint:

    • POST {PUB_SERVER_URL}/auth/api/loginToPubserver

  • Content-Type:

    • application/x-www-form-urlencoded

Form Parameters​

ParameterDescription
appApplication name. For AdminAPI integrations, use admin.
usernamePubServer username.
passwordPassword of the PubServer user.
projectTarget project.

Example Request​

curl -X POST \
  '{PUB_SERVER_URL}/auth/api/loginToPubserver' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'app=admin' \
  -d 'username=admin' \
  -d 'password=password' \
  -d 'project=aio'

If the credentials are valid, a session ID is returned in the response body and is also stored in the adminSessionId cookie.

Example Response​

{
  "cookies": [
    {
      "name": "adminSessionId",
      "value": "10e2c832-f8f6-4e65-a647-60ee467e2967"
    }
  ],
  "loginStatus": "LOGGED",
  "session": "10e2c832-f8f6-4e65-a647-60ee467e2967"
}

Step 2: Exchange the Session ID for an AdminAPI Token​

After obtaining a valid session ID, exchange it for an AdminAPI token.

Request​

  • Endpoint:

    • GET {PUB_SERVER_URL}/AdminAPI/api/auth/login/{SESSION_ID}

Example Request​

curl -X GET \
  '{PUB_SERVER_URL}/AdminAPI/api/auth/login/{SESSION_ID}'

If the session ID is valid, the AdminAPI token is returned in the response and is also stored in the adminToken cookie.

Example Response​

{
  "sessionInfo": {
    "entityModelIdentifier": "DefaultProject",
    "lang": "en",
    "login": "admin",
    "project": "aio",
    "sessionId": "10e2c832-f8f6-4e65-a647-60ee467e2967",
    "token": "<JWT_TOKEN>",
    "trace": false
  }
}

Using the API Token​

Once obtained, the AdminAPI token must be included in every AdminAPI request.

Provide the token using the Authorization header:

Authorization: Bearer <JWT_TOKEN>

Example:

curl -X GET \
  'https://{PUB_SERVER_DOMAIN}/AdminAPI/api/users' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <JWT_TOKEN>'

Provide the token using the adminToken cookie:

Cookie: adminToken=<JWT_TOKEN>

Example:

curl -X GET \
  'https://{PUB_SERVER_DOMAIN}/AdminAPI/api/users' \
  -H 'Accept: application/json' \
  -H 'Cookie: adminToken=<JWT_TOKEN>'

Token Expiration and Reauthentication​

The AdminAPI token has a limited lifetime. Once the token expires, requests authenticated with that token will be rejected.

Expired Token​

If an API request is made with an expired or invalid token, the server will return an authentication error (typically 401 Unauthorized).

Example:

HTTP/1.1 401 Unauthorized

Obtaining a New Token​

When a token expires, clients should repeat the authentication flow:

  1. Request a new PubServer session ID.
  2. Exchange the session ID for a new AdminAPI token.
  3. Retry the failed request using the new token.

Session Validation​

The AdminAPI token is linked to the underlying PubServer session. If the PubServer session becomes invalid or expires, a new session must be created before a new AdminAPI token can be obtained.

Error Handling​

The following table describes common authentication-related errors.

HTTP StatusDescriptionRecommended Action
400 Bad RequestInvalid request parameters.Verify the request format and required parameters.
401 UnauthorizedMissing, invalid, or expired API token.Obtain a new API token and retry the request.
403 ForbiddenThe authenticated user does not have permission to access the requested resource.Verify the user's permissions and roles.
404 Not FoundThe requested endpoint or resource does not exist.Verify the endpoint URL.
500 Internal Server ErrorAn unexpected server-side error occurred.Retry later or contact the system administrator if the problem persists.

Common Authentication Failures​

Authentication may fail for one of the following reasons:

  • Invalid username or password.
  • Invalid or expired PubServer session.
  • Invalid or expired AdminAPI token.
  • Missing authentication information.

Clients should treat authentication failures as non-recoverable unless a new session and token are obtained.

Security Recommendations​

To protect user credentials and API tokens, follow these recommendations:

  • Always use HTTPS for authentication and API requests.
  • Treat API tokens as sensitive credentials.
  • Never store passwords or API tokens in source code repositories.
  • Never expose API tokens in URLs, logs, screenshots, or client-side code.
  • Use the Authorization header whenever possible instead of cookies for server-to-server integrations.
  • Clear stored tokens when users log out.
  • Rotate credentials according to your organization's security policies.