DOCSEARCHbyAlgolia
Submit Docs

Phase Two API Documentation

website·Indexed 33 days ago

https://phasetwo.io/

Technical specifications for the Phase Two Admin REST API and Cluster Management API. Includes OpenAPI 3.0.2 and 3.0.3 definitions for managing Keycloak custom resources, extensions, hosted Keycloak clusters, custom hostnames, and DNS/TLS provisioning.

Tokens
14.9K
Snippets
118
Records
131
Agent score
20%

What's inside Phase Two

  1. Manage API Secrets for Service Accounts

    API Secrets allow service accounts to authenticate using the OAuth2 client credentials grant. When creating a secret via SecretRequest, the name must be unique within the organization, maximum 32 characters, and contain only lowercase letters. The roles granted to the secret must be a subset of the roles already held by the calling user.
    // SecretRequest
{
  "name": "my-service-account",
  "roles": ["admin", "viewer"]
}

// Secret Response
{
  "id": "secret-id",
  "client_id": "oauth-client-id",
  "client_secret": "********", // Only visible on first creation
  "roles": ["admin"]
}

  2. Upload and confirm an extension version jar

    Uploading an extension version is a two-step process:

    1. Request Upload URL: Obtain a presigned S3 URL to upload the jar file.
    2. Confirm Upload: Verify the jar was uploaded to the presigned URL and record its location. If extension scanning is enabled for the cluster, this step also queues a security scan of the jar.
    # Step 1: Get presigned URL
POST /clusters/{id}/extensions/{extensionId}/versions/{versionId}/upload-url

# Step 2: Confirm the upload
PUT /clusters/{id}/extensions/{extensionId}/versions/{versionId}/confirm

  3. Create a dedicated cluster and handle payment

    When creating a dedicated cluster via POST /clusters, provisioning begins after payment is settled. The API response will indicate one of three states:

    1. link: A Stripe Checkout URL is provided for payment setup (occurs if payment_method_id is omitted).
    2. cluster: An existing payment method was charged successfully and the cluster is created.
    3. requires_action: The payment requires 3DS/SCA authentication. Use the provided client_secret and cluster_id with Stripe.js to complete the payment.

  4. Upload Extension Jars via Presigned URLs

    To upload an extension jar, the API provides a PresignedUrl object containing a short-lived S3 target. The developer must use the specified HTTP method (e.g., PUT) to upload the file to the url. The resourceKey returned in this object must be passed back to the corresponding confirm operation to finalize the upload.
    {
  "url": "https://s3...",
  "method": "PUT",
  "resourceKey": "unique-resource-identifier"
}

  5. Upload and validate Keycloak extension versions

    The API provides a workflow for managing Keycloak extensions. This involves requesting an upload URL, uploading the JAR file to S3, and validating the resource key. When creating an extension version, you must specify the target Keycloak major version, which must match a value returned by cluster.extension.keycloakVersion.list.
    // ExtensionVersionRequest
{
  "keycloak_major_version": 22
}

// ExtensionVersionLocationValidationRequest
{
  "resource_key": "s3-object-key-from-upload-url"
}

  6. Manage organization payment methods

    List saved Stripe card payment methods or create a Stripe Checkout session to add a new payment method. A payment method currently in use by an active subscription cannot be removed. Creating a setup session requires manage-billing permissions.

    GET /orgs/{orgId}/billing/payment-methods POST /orgs/{orgId}/billing/payment-methods

  7. Authenticate with the Phase Two Cluster Management API

    All requests to the Cluster Management API require an OAuth2 access token obtained via the client credentials grant. You must first create an API secret for your organization (via the console's API Credentials tab or the org.apiSecret.create endpoint). The resulting token must be sent in the Authorization: Bearer <token> header. Permissions are governed by organization roles assigned to the API secret, not by OAuth scopes.
    curl -X POST https://app.phasetwo.io/auth/realms/self/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id=$PHASETWO_CLIENT_ID \
  -d client_secret=$PHASETWO_CLIENT_SECRET

  8. Authenticate with Phase Two Cluster Management API

    The Phase Two Cluster Management API uses OIDC client credentials for authentication. To authenticate, you must first obtain a client ID and secret pair using the org.apiSecret.create operation. These credentials are then exchanged for an access token at the environment-specific token URL.

    Production Token URL

    https://app.phasetwo.io/auth/realms/self/protocol/openid-connect/token

    Staging Token URL

    https://app-staging.phasetwo.io/auth/realms/self/protocol/openid-connect/token

  9. Manage .well-known app association files for custom domains

    The Phase Two Cluster Management API allows you to manage app association files (like apple-app-site-association or assetlinks.json) for custom domains. The process involves creating a presigned upload URL, uploading the file, and then confirming the upload to validate and publish it.
    # 1. Create a presigned upload URL
POST /clusters/{id}/extensions/{extensionId}/well-known/{file}/upload-url

# 2. Upload the file using the returned URL via PUT

# 3. Validate and publish the uploaded file
PUT /clusters/{id}/extensions/{extensionId}/well-known/{file}/confirm

  10. Upload a standalone extension JAR

    To upload a version-independent standalone extension, follow this two-step process:

    1. Request a presigned S3 upload URL. Use the returned URL to PUT the JAR file.
    2. Call the confirm operation to verify the upload and make the extension available for deployment.

    POST /clusters/{id}/extensions/{extensionId}/standalone (Get upload URL) PUT /clusters/{id}/extensions/{extensionId}/standalone/confirm (Finalize upload)

  11. Authenticate requests to the Phase Two Admin REST API

    Authentication for the Phase Two Admin REST API is performed using a Bearer token in the HTTP request header. You can obtain this token via a standard authentication flow or by calling the OpenID Connect token endpoint directly.

    Required Header: Authentication: Bearer <token>

    It is recommended to use a Keycloak Admin Client (e.g., the JavaScript client) to handle token acquisition and automatic refreshing.

    Client credentials grant example

    POST /auth/realms/test-realm/protocol/openid-connect/token
Host: app.phasetwo.io
Accept: application/json
Content-type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=admin-cli&client_secret=fd649804-3a74-4d69-acaa-8f065c6b7da1

    Password grant example

    POST /auth/realms/test-realm/protocol/openid-connect/token
Host: app.phasetwo.io
Accept: application/json
Content-type: application/x-www-form-urlencoded

grant_type=password&username=uname@foo.com&password=pwd123AZY&client_id=admin-cli

  12. Configure custom environment variables for Keycloak deployments

    Custom environment variables can be set on a cluster's Keycloak deployment using the EnvironmentVariableRequest object.

    Constraints:

    • Variable names must not start with KC_ unless they start with KC_SPI_ (only custom SPI configuration is permitted).
    • Values are stored in AWS Parameter Store.
    • STRING types are plain text; SECRET types are encrypted and masked on read.
    {
  "name": "string",
  "value": "string",
  "type": "STRING" | "SECRET"
}