API

The Phase HTTP REST API allows you to manage secrets programmatically via an HTTP client. The API enables you to create, fetch, update, and delete secrets across all your Apps, Environments, and Folders.

Overview

You can use the Phase public REST API to access and manage secrets via a simple HTTP endpoint. This may be desirable when accessing secrets in clients that do not have the ability to execute client-side logic necessary for secure secret management and must rely on the server to do so.

The Phase API is organized around REST. The API accepts data in the request body only in JSON-encoded format. It uses standard HTTP methods and response codes.

The API also returns specific error messages when something goes wrong. Check out the API errors page for more details.

Base URL

If you are using Phase Cloud, the API can be accessed at https://api.phase.dev. Alternatively, if you are self-hosting Phase, the API is by default exposed at ${HTTP_PROTOCOL}${HOST}/service/public.

Example:

curl https://api.phase.dev/v1/secrets/?app_id=<app_id>&env=development \
  -H "Authorization: Bearer {token}"

Authentication

All API requests must be authenticated with a bearer token in the Authorization header of each request, followed by the type of token used and the token. You can find more information about the token types here.

When deciding between authentication token types, you may consider:

• Service Account Token: Belongs to a Service Account. Inherits the Access Control policies and Roles from a service account.
• Personal Access Token (PAT): Belongs to a human user. Inherits the Access Control policies and Roles from a user. Has access to all Apps and Environments that a particular user has access to. Will return any Personal Secret Overrides you might have set for a given secret.

Example:

curl https://api.phase.dev/v1/secrets/?app_id=8d8fde43-ceb6-4c92-a776-827433512ff9&env=production \
  -H "Authorization: Bearer ServiceAccount ac671c7556ec51cec52baa15168339dcbe96b360f81575873d0c31607148f378"

Encryption Mode

Certain API endpoints that allow manipulation of encrypted data such as Secrets require Server-side Encryption (SSE) to be enabled for the App. You can enable SSE for an App from the App settings page.

Rate Limits

The Phase Cloud API enforces rate limiting to ensure fair usage and maintain optimal performance for all users. The following standard rate limits apply, based on your Organisation's plan:

If you exceed the allowed number of requests within a given time frame, you will receive a 429 Too Many Requests response. The response will include information about when you can retry your request in the retry-after header.

HTTP/2 429 
server: nginx
date: Fri, 05 Dec 2025 07:18:01 GMT
content-type: application/json
content-length: 68
retry-after: 52
allow: GET, POST, PUT, DELETE, HEAD, OPTIONS
x-frame-options: DENY
vary: Origin
x-content-type-options: nosniff
referrer-policy: same-origin
cross-origin-opener-policy: same-origin

Self-hosted Phase instances do not enforce rate limiting by default. However, administrators can configure rate limiting based on their requirements via the RATE_LIMIT_DEFAULT environment variable. Please see the self-hosting deployment configuration documentation for more details.