AuthN API Credentials

To access AuthN APIs , create service tokens or use OAuth 2 clients.

To manage access, go to the service page in your Pangea User Console and click API Credentials in the left-hand navigation sidebar.

Service Tokens

You can manage service API tokens under the Service Tokens tab on the AuthN API Credentials page.

Service API tokens are used as bearer tokens to authorize access to Pangea service APIs. They are provisioned per project and can grant full or partial access to one or more services. Pangea recommends limiting the token scope to only what your application requires.

Token list

When you enable AuthN, you can create a service token associated with it. This token appears in the Service Tokens list and is marked as the Default Token. The default token is also shown on the service Overview page. Any additional tokens associated with the service are also listed.

In the service token list, you can:

• View and copy the token value.
• Go to the Vault page to define the token rotation policy, rotate the token manually, copy its Vault ID, view token versions, and enable or disable the token. You can use the token ID to retrieve its value dynamically using the Vault APIs in your application.
• Set the token to be watched for changes.
• Access additional actions via the triple-dot menu:
  • Set as default - Designate this token as the default for the service.
  • Edit token - Update token scopes or associate the token with other enabled services.
  • Copy token - Use this token as a template to create a new one.
  • Delete token - Revoke access granted by this token.

Create or update token

Click the Create token button or select Copy token from the triple-dot menu to define a new token. To update an existing token, select Edit token from the menu.

• Token Name - A readable identifier shown in the Name column of the token list, as well as in charts and metrics that track token usage.
• Token Expiration Date - To help reduce the risk of token leakage, set an expiration date to limit the token’s lifespan.
• Select your services and endpoints - Choose one or more enabled services this token can access. If a service supports fine-grained access, a gear icon appears next to its name. Click the gear icon to configure:
  • Manage Endpoint Access - Grant access to all or selected endpoints of the service. Hover over a scope to see the endpoints it enables.
  • Manage Config Access (for services that support multiple configurations) - The Secure Audit Log and Redact services support multiple configurations to handle different use cases within a single Pangea project. You can associate the token with one or more of these configurations. Learn more in the Secure Audit Log documentation.
  • Manage Field Restrictions (Secure Audit Log only) - Each Secure Audit Log configuration has its own schema. You can restrict token access to specific schema fields within the associated configurations.

Click the Create token or Update token button in the dialog to apply your changes.

Create service token

Service token configuration options for AuthN

Service Clients

Click the Service Clients tab to manage service API tokens using OAuth 2 clients.

Service-level OAuth 2 clients can issue access tokens using the Client Credentials grant to authorize full or partial access to the APIs of one or more Pangea security services. Pangea recommends limiting the scope of each access token to only what your application requires.

The client list includes all clients that can grant access to the AuthN APIs.

Create service client

1. Click the Create service client button.

2. In the Create a client dialog, configure the client:

   • Name - Enter a name that will appear in the Client Name column in the client list. The name must be unique within the project.
   • Platform Client secret rotates every - Specify how often the client secret is rotated in Vault.
   • Access tokens expire in - Set the lifetime of access tokens issued by the client.
   • Select services - Choose one or more enabled services that tokens from this client can access. After selecting a service, click the gear icon to select the scope values the client can request to access the service's API endpoints.

3. Click Create client.

Create service client

Select the role and scope for the service client

Client details

The new client ID and secret, along with the Create access token button, are shown in a temporary view. Once closed, this view cannot be reopened. However, you can:

• Use the client list table to copy the client ID and secret and view other client details.
• Use the key link to configure the client secret rotation policy in Vault.
• Use the triple-dot menu to create a new access token, generate a new client secret, or delete the client.
• Click a client row to view its details in the right-hand panel, update its configuration, or create new secrets.

Temporarily displayed new client details

Client details page

Client Credentials grant

Your application can use the endpoints returned by the Service & Management Clients' OAuth Authorization Server Metadata endpoint to obtain access tokens using the Client Credentials grant and to revoke authorization.

GET /.well-known/oauth-authorization-server

curl --location 'https://authorization.access.aws.us.pangea.cloud/.well-known/oauth-authorization-server'

{
  "grant_types_supported": [
    "client_credentials"
  ],
  "introspection_endpoint": "https://authorization.access.aws.us.pangea.cloud/v1beta/oauth/token/introspect",
  "issuer": "https://authorization.access.aws.us.pangea.cloud",
  "response_types_supported": [
    "token"
  ],
  "revocation_endpoint": "https://authorization.access.aws.us.pangea.cloud/v1beta/oauth/token/revoke",
  "scopes_supported": [
    "pangea:platform:account:read",
    "pangea:platform:account:write",
    ...
    "pangea:service:vault:sign",
    "pangea:service:vault:config:manage",
    "pangea:service:vault:config:read"
  ],
  "token_endpoint": "https://authorization.access.aws.us.pangea.cloud/v1beta/oauth/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post"
  ]
}

Authorize client requests

By default, a new client is registered with the client_secret_basic authentication method.

note

You can use the Service & Management Clients APIs to register a Platform Client with the client_secret_post authentication method instead.

Learn more about registering a service client in the Project API Credentials documentation.

In the following example, we'll use the default HTTP Basic Authentication scheme to authenticate the client.

1. Set the environment.

   Set environment variables

   export PANGEA_CLIENT_ID="psa_hd5cnx3sh64jrz3ruu6r4t4jsk2zj6nn"
   export PANGEA_CLIENT_SECRET="pck_65mjv4...imykaf"

2. Concatenate the client ID and client secret with a colon (:) and base64 encode the result.

   tip

   On a Linux-based system, you can use the base64 utility to encode the client credentials:

   Use HTTP Basic authentication scheme for authenticating a client

   export PANGEA_BASIC_AUTHENTICATION_CREDENTIAL=$(echo -n $PANGEA_CLIENT_ID:$PANGEA_CLIENT_SECRET | base64)

3. Add the Base64-encoded string to the request's Authorization header, prefixed with "Basic ".

4. Provide the following parameters in the "application/x-www-form-urlencoded" format:

   • grant_type - Set to "client_credentials".

   • scope (optional) - A space-delimited list of scope values defining which endpoints the token can access.

     If you include the scope parameter, the token will be limited to the specified subset of client permissions. If scope is omitted, the token will inherit all permissions granted to the client.

Request access token

export PANGEA_TOKEN_ENDPOINT="https://authorization.access.aws.us.pangea.cloud/v1beta/oauth/token"

POST /v1beta/oauth/token

curl --location "$PANGEA_TOKEN_ENDPOINT" \
--header "Authorization: Basic $PANGEA_BASIC_AUTHENTICATION_CREDENTIAL" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=pangea:service:authn:user:read pangea:service:authn:user:manage'

The response includes the access token, its expiration time, and the scope granted to the token.

/v1beta/oauth/token response

{
  "access_token": "pts_goysqe...e4m6ei",
  "token_type": "Bearer",
  "expires_in": 3599,
  "scope": "pangea:service:authn:user:read pangea:service:authn:user:manage"
}

Introspect access token

Optionally, you can verify whether the access token is active and check its scope before making an API request.

export PANGEA_INTROSPECTION_ENDPOINT="https://authorization.access.aws.us.pangea.cloud/v1beta/oauth/token/introspect"

POST /v1beta/oauth/token

curl --location "$PANGEA_INTROSPECTION_ENDPOINT" \
--header "Authorization: Basic $PANGEA_BASIC_AUTHENTICATION_CREDENTIAL" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode "token=$PANGEA_ACCESS_TOKEN"

A properly authorized introspection request for an active token returns token information with the active key set to true.

/v1beta/oauth/token response

{
  "iss": "https://authorization.access.aws.us.pangea.cloud",
  "sub": "pui_55ljz3kllliqrl43pxdgho4bk62qibzk",
  "exp": 1745551598,
  "nbf": 1745547998,
  "iat": 1745547998,
  "jti": "pmt_kzicrsqfdarghh4ilmfpm65fqzmk7dbg",
  "client_id": "psa_cafxenjprgcrggnfl4o7kznrjmlfi746",
  "token_type": "Bearer",
  "username": "AuthN Client",
  "scope": "pangea:service:authn:user:read pangea:service:authn:user:manage",
  "active": true
}

If the token is inactive, invalid, or the request is unauthorized, the response contains only the active key set to false.

/v1beta/oauth/token response for an inactive token, invalid token, or failed introspection request

{
  "active": false
}

Revoke access

export PANGEA_REVOCATION_ENDPOINT="https://authorization.access.aws.us.pangea.cloud/v1beta/oauth/token/revoke"

POST /v1beta/oauth/token

curl --location "$PANGEA_REVOCATION_ENDPOINT" \
--header "Authorization: Basic $PANGEA_BASIC_AUTHENTICATION_CREDENTIAL" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode "token=$PANGEA_ACCESS_TOKEN"

A successful revocation request returns HTTP status code 200 with no response body.

If the request succeeds but revocation fails, the response body will include details about the error.

/v1beta/oauth/token not found response

{
  "error": "invalid_request",
  "error_description": "The token does not exist"
}

Service APIs

Once you have a service token or an access token issued by a Service Client with access to the service APIs, you can make it available to your application and use it to authorize requests by passing it as a bearer token.

For example, you can use the /v2/user/list endpoint to retrieve the list of users in your project.

export PANGEA_DOMAIN="aws.us.pangea.cloud"
export PANGEA_ACCESS_TOKEN="pts_goysqe...e4m6ei"

POST /v2/user/list

curl --location "https://authn.$PANGEA_DOMAIN/v2/user/list" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $PANGEA_ACCESS_TOKEN" \
--data '{
  "filter": {
    "email__contains": [
      "@ingen.com"
    ]
  }
}'

/v2/user/list response

{
  "status": "Success",
  "summary": "Listed users",
  "result": {
    "users": [
      {
        "id": "pui_57opch7rs2meq4lf2gmtapl44moyl37k",
        "username": "dennis.nerdy",
        "email": "dennis.nedry@ingen.com",
        "phone": "",
        "profile": {
          "first_name": "Dennis",
          "last_name": "Nedry"
        },
        "verified": true,
        "disabled": false,
        "locked_out": false,
        "last_login_at": "1993-06-10T02:06:17.010210Z",
        "created_at": "1987-11-01T02:05:21.435373Z",
        "login_count": 1024,
        "last_login_ip": "107.179.36.0",
        "last_login_city": "Chacarita",
        "last_login_country": "Costa Rica",
        "authenticators": [
          {
            "id": "pau_u5mgccytzv6bynvimirjd2p4dw6c3iwa",
            "type": "password",
            "enabled": true,
            "phase": "primary",
            "enrolling_browser": "xterm on SunOS 3.5 via rlogin",
            "enrolling_ip": "12.237.192.97",
            "created_at": "1987-11-01:05:21.436905Z",
            "updated_at": "1987-11-01:05:21.436905Z",
            "state": "active"
          },
          {
            "id": "pau_qbv6nsj52vj2f34kpisn3pltumtm7ucz",
            "type": "email_otp",
            "enabled": true,
            "phase": "secondary",
            "enrolling_browser": "xterm on SunOS 3.5 via rlogin",
            "enrolling_ip": "12.237.192.97",
            "created_at": "1987-11-01T02:06:16.920575Z",
            "updated_at": "1987-11-01T02:06:16.918841Z",
            "state": "active"
          }
        ]
      },
      ...
    ],
    "last": "MTox",
    "count": 19
  },
  ...
}

tip

If request processing takes longer than expected, an additional network request is required to retrieve the result. If you receive a 202 Accepted status code in the original response, use the URL provided in the location field under the result key to poll for the result.

For security reasons, you must use the same access token as in the original request.

For example:

202 Accepted response

{
  "status": "Accepted",
  "summary": "Your request is in progress. Use 'result.location' below to poll for results. See https://dev.pangea.cloud/docs/api/async?service=<service-name>&request_id=prq_7ohu4d5yxkdyqn75xoutueg3qnufdl3u for more information.",
  "result": {
    "location": "https://<service-name>.aws.us.pangea.cloud/request/prq_7ohu4d5yxkdyqn75xoutueg3qnufdl3u",
    "retry_counter": 0,
    "ttl_mins": 5760
  },
  ...
}

export PANGEA_LOCATION_URL="https://<service-name>.aws.us.pangea.cloud/request/prq_s5qrrscqsgnhlmbr2b64xqlo7g5yi6mf"

Poll location

curl --location GET "${PANGEA_LOCATION_URL}" \
-H "Authorization: Bearer ${PANGEA_ACCESS_TOKEN}" \
-H 'Content-Type: application/json'

Learn more in the Asynchronous API Responses documentation.

Was this article helpful?

Contact us