API

External Identities

Authenticate to Phase using external identity providers. Each provider returns a Phase authentication token scoped to the specified Service Account, with an optional TTL.

AWS IAM

POST/identities/external/v1/aws/iam/auth/

Authenticate with AWS IAM

Exchange an AWS STS SigV4-signed GetCallerIdentity request for a Phase token.

JSON Body

Supply the Service Account to authenticate and the signed AWS request data.

Required fields

Name
account.id
Type
string
Description
Service Account ID (UUID) to authenticate.
Name
awsIam.httpRequestUrl
Type
string
Description
Base64-encoded signed request URL (from SigV4 prepared request).
Name
awsIam.httpRequestHeaders
Type
string
Description
Base64-encoded JSON of signed request headers.
Name
awsIam.httpRequestBody
Type
string
Description
Base64-encoded request body used to sign the GetCallerIdentity call.

Optional fields

Name
account.type
Type
string
Description
Defaults to service. Only service is supported currently.
Name
awsIam.httpRequestMethod
Type
string
Description
HTTP method used when signing. Defaults to POST.
Name
tokenRequest.ttl
Type
number
Description
Requested token TTL in seconds. If omitted, the default identity TTL is used.

To create the signed values, sign an AWS STS GetCallerIdentity request with SigV4 for your region/endpoint. Use the STS Query API body Action=GetCallerIdentity&Version=2011-06-15 and header Content-Type: application/x-www-form-urlencoded; charset=utf-8. Then Base64-encode the prepared URL, headers (as JSON), and body.

Request

POST

/identities/external/v1/aws/iam/auth/

{
  "account": {
    "type": "service",
    "id": "00000000-0000-0000-0000-000000000000"
  },
  "awsIam": {
    "httpRequestMethod": "POST",
    "httpRequestUrl": "<base64>",
    "httpRequestHeaders": "<base64>",
    "httpRequestBody": "<base64>"
  },
  "tokenRequest": {
    "ttl": 3600
  }
}

Response

{
  "authentication": {
    "tokenType": "ServiceAccount",
    "token": "pss_service:v2:...",
    "bearerToken": "ServiceAccount baca69c634d84e5d3d04d31a487eb1c4c5f2a3ef2a6683f77cf965d3ad7633d3",
    "TTL": 3600,
    "maxTTL": 86400
  }
}

Notes on signing the AWS request

Use AWS SigV4 to sign an STS GetCallerIdentity request.

Name
Endpoint
Type
string
Description
Prefer the regional STS endpoint for your configured AWS region (e.g. https://sts.eu-central-1.amazonaws.com). If no region is found, you may use the legacy global endpoint.
Name
Method
Type
string
Description
POST (default) or GET. The same method must be used in signing and in awsIam.httpRequestMethod.
Name
Body
Type
string
Description
STS Query API payload: Action=GetCallerIdentity&Version=2011-06-15.
Name
Headers
Type
object
Description
Must include Content-Type: application/x-www-form-urlencoded; charset=utf-8 and SigV4 headers (e.g. X-Amz-Date, Authorization).

Base64-encode the prepared URL, headers (as JSON), and body before submitting to Phase.

Azure

POST/identities/external/v1/azure/entra/auth/

Authenticate with Azure

Exchange an Azure AD JWT for a Phase token. The JWT is validated statelessly using Azure AD's public OIDC signing keys — no Azure credentials are stored on the Phase backend.

JSON Body

Supply the Service Account to authenticate and the base64-encoded Azure AD JWT.

Required fields

Name
account.id
Type
string
Description
Service Account ID (UUID) to authenticate.
Name
azureEntra.jwt
Type
string
Description
Base64-encoded Azure AD JWT access token.

Optional fields

Name
account.type
Type
string
Description
Defaults to service. Only service is supported currently.
Name
tokenRequest.ttl
Type
number
Description
Requested token TTL in seconds. If omitted, the default identity TTL is used.

The JWT must be obtained from Azure AD with a resource / audience that matches the value configured on the Phase identity (default: https://management.azure.com/). The oid claim in the JWT (the service principal's object ID) must be in the identity's allowed service principal IDs list.

Request

POST

/identities/external/v1/azure/entra/auth/

{
  "account": {
    "type": "service",
    "id": "00000000-0000-0000-0000-000000000000"
  },
  "azureEntra": {
    "jwt": "<base64-encoded-jwt>"
  },
  "tokenRequest": {
    "ttl": 3600
  }
}

Response

{
  "authentication": {
    "tokenType": "ServiceAccount",
    "token": "pss_service:v2:...",
    "bearerToken": "ServiceAccount baca69c634d84e5d3d04d31a487eb1c4c5f2a3ef2a6683f77cf965d3ad7633d3",
    "TTL": 3600,
    "maxTTL": 86400
  }
}

Notes on Azure JWT tokens

Azure AD issues two token versions. The version is determined by the accessTokenAcceptedVersion on the resource app registration, not the client.

Name
v1.0 tokens (default)
Type
string
Description
Used for https://management.azure.com/. Issuer: https://sts.windows.net/{'{'}tenantId{'}'}/. Audience: resource URI string.
Name
v2.0 tokens
Type
string
Description
Used for custom app registrations with accessTokenAcceptedVersion: 2. Issuer: https://login.microsoftonline.com/{'{'}tenantId{'}'}/v2.0. Audience: client ID GUID.
Name
Credential sources
Type
string
Description
DefaultAzureCredential tries (in order): environment variables (Service Principal), Workload Identity (Kubernetes), Managed Identity (IMDS), Azure CLI, Azure Developer CLI.

Phase automatically detects the token version and validates accordingly. No configuration is needed.