diff --git a/docs/menu.cue b/docs/menu.cue index 153343b5fe..efed95ba36 100644 --- a/docs/menu.cue +++ b/docs/menu.cue @@ -732,6 +732,16 @@ text: "Webhooks" path: "/deploy/webhooks" file: "deploy/webhooks" + }, { + kind: "basic" + text: "OAuth Clients" + path: "/platform/oauth-clients" + file: "platform/oauth-clients" + }, { + kind: "basic" + text: "API Reference" + path: "/platform/api-reference" + file: "platform/api-reference" }] } diff --git a/docs/platform/api-reference.md b/docs/platform/api-reference.md new file mode 100644 index 0000000000..ad5c878f3b --- /dev/null +++ b/docs/platform/api-reference.md @@ -0,0 +1,167 @@ +--- +seotitle: Encore Platform API Reference +seodesc: Learn how to use the Encore Platform API. +title: Platform API Reference +--- + +The Encore Platform provides an API for programmatic access to control certain parts of the platform. + +We're working on expanding the set of features available over the API. +Please reach out to us [on Discord](https://encore.dev/discord) if you have use cases where additional API functionality would be useful. + +The Base URL for the Encore Platform API is `https://api.encore.dev`. + +## Authentication + +All API calls require valid authentication, which is provided by sending an access token in the `Authorization` header, +in the format `Authorization: Bearer ${ACCESS_TOKEN}`. + +You can retrieve an API access token from the OAuth Token endpoint, using an OAuth Client. +An API access token expires after one hour. For continuous access, shortly before an API access token expires, request a new API access token from the Encore Platform's OAuth token endpoint. + +OAuth client libraries in popular programming languages can handle the API access token generation and renewal. + +See the [OAuth Clients](/docs/platform/oauth-clients) for more information on creating OAuth Clients. + +## OAuth + +**Method**: `POST`
+**Path**: `/api/oauth/token` + +#### Query Parameters + +| Parameter | Description | +| ----------------- | -------------------------------------------------------------- | +| **client_id** | The client id of the OAuth Client to generate a token for. | +| **client_secret** | The client secret of the OAuth Client to generate a token for. | + +#### Response + +The API responds with a 2xx status code on successful creation of an API access token. + +```typescript +type Token = { + // The access token itself. + "access_token": string; + + // The access token expires after 1 hour (3600 seconds). + "expires_in": 3600; + + // The actor the token belongs to, in this case the OAuth2 client id. + actor: string; + + + // Indicates the access token should be passed as a "Bearer" token in the Authorization header. + "token_type": "Bearer"; +} +``` + +## Rollouts + +The Encore Platform's deployment system consists of several phases: + +* A build phase +* An infrastructure provisioning phase +* A deployment phase + +These phases are combined into a unified entity called a *Rollout*. +A rollout represents the coordinated process of rolling out a specific version of an Encore application. + +We use the term *rollout* to disambiguate from the *deployment phase*, which specifically +refers to the last phase of the rollout process (where the version is being deployed onto the provisioned infrastructure). + +### The Rollout Object + +The Rollout object represents the state of a rollout. + +```typescript +// The representation of a rollout. +type Rollout = { + // Unique id of the rollout. + id: string; + + // The current status of the rollout. + status: "pending" | "queued" | "running" | "completed"; + + // What the conclusion was of the rollout (when status is "completed"). + // If the status is not "completed" the conclusion is "pending". + conclusion: "pending" | "canceled" | "failure" | "success"; + + // When the rollout was queued, started, and completed. + queued_at: Date | null; + started_at: Date | null; + completed_at: Date | null; + + // Information about the various rollout phases. + // See type definitions below. + build: RolloutPhase; + infra: RolloutPhase; + deploy: RolloutPhase; +} + +// Common structure of the various rollout phases. +type RolloutPhase = { + // Unique id of the phase. + id: string; + + // The current status of the rollout phase. + status: Status; + + // What the conclusion was of the phase. + conclusion: Conclusion; + + // When the phase was queued, started, and completed. + queued_at: Date | null; + started_at: Date | null; + completed_at: Date | null; +} + +// The current status and conclusion of a build. +// If the status is not "completed" the conclusion is "unknown". +type BuildStatus = "queued" | "running" | "completed"; +type BuildConclusion = "unknown" | "canceled" | "failure" | "success"; + +// The current status and conclusion of an infra change. +// The "proposed" status means the change is awaiting human approval. +// The "rejected" conclusion means a human rejected the proposed infra change. +type InfraStatus = "pending" | "proposed" | "queued" | "running" | "completed"; +type InfraConclusion = "unknown" | "canceled" | "failure" | "rejected" | "success"; + +// The current status and conclusion of a deploy. +// If the status is not "completed" the conclusion is "unknown". +type DeployStatus = "queued" | "running" | "completed"; +type DeployConclusion = "unknown" | "canceled" | "failure" | "success"; +``` + +### Triggering a rollout + +**Method**: `POST`
+**Path**: `/api/apps/${APP_ID}/envs/${ENV_NAME}/rollouts` + +#### Path Parameters + +| Parameter | Description | +| ------------ | ---------------------------------------------------------- | +| **APP_ID** | The id of the Encore application to trigger a rollout for. | +| **ENV_NAME** | The name of the environment to trigger a rollout for. | + +#### JSON Request Body +A rollout can be triggered either with a commit sha or the name of a branch, +depending on the JSON field passed in. Exactly one of these must be provided. + +```typescript +{ + // The commit hash to trigger a deploy for. + "sha": string; +} | { + // Name of the branch to trigger a deploy from. + "branch": string; +} +``` + +#### Response + +The API responds with a 2xx status code on successful creation of a new rollout. + +On success it returns a **Rollout** object as its JSON response payload, +representing the current state of the newly created rollout. diff --git a/docs/platform/oauth-clients.md b/docs/platform/oauth-clients.md new file mode 100644 index 0000000000..1093f3422d --- /dev/null +++ b/docs/platform/oauth-clients.md @@ -0,0 +1,116 @@ +--- +seotitle: Encore Platform OAuth Clients +seodesc: Learn how to use OAuth Clients for access to the Encore Platform API +title: OAuth Clients +--- + +OAuth clients provide a framework for delegated and scoped access to the Encore Platform API. An OAuth client creates short-lived access tokens on demand, and supports the principle of least privilege by allowing fine-grained control on the access granted to the client using scopes. + +## How it works +You create an OAuth client that defines the scopes to allow when your client application uses the Encore Platform API. + +Scopes are currently grouped into "roles", which include a set of permissions. +For example, the `deployer` role grants access to the triggering deployments. + +An OAuth client consists of a client ID and a client secret. When you create an OAuth client, the Encore Platform creates these for you. Within your client application, use the client ID and client secret to request an API access token from the Encore Platform's OAuth token endpoint. You use the access token to make calls to the Encore Platform API. The access token grants permission only for the scopes that were defined when you created the OAuth client. + +An API access token expires after one hour. For continuous access, shortly before an API access token expires, request a new API access token from the Encore Platform's OAuth token endpoint. + +OAuth client libraries in popular programming languages can handle the API access token generation and renewal. + +The Encore Platform's OAuth implementation is based on the [OAuth 2.0 protocol](https://www.rfc-editor.org/rfc/rfc6749). + +## Prerequisites +You need to be an Owner of the Encore application in order to create or revoke OAuth clients. + +### Setting up an OAuth client +Open the OAuth clients page in the application settings page. + +In the Generate OAuth client dialog, select the set of operations that can be performed with tokens created by the new OAuth client. + +After generating the client, you can see the new OAuth client's ID and secret. Copy both the client ID and secret, as you need them for your client code. +Note that after you close the Generated new OAuth client dialog, you won't be able to copy the secret again. +**Store the client secret securely.** + +Your OAuth client is now configured. Use the client ID and secret when you configure your OAuth client application. Note that the provided client secrets are case-sensitive. + +If an OAuth client is created by a user who is later removed from your application, the OAuth client will continue to function and generate API access tokens. +Application owners can see all configured OAuth clients in the OAuth clients page of the application settings. + +### Roles +Roles define which operations are permitted in API access tokens that are created by your client application. + +Currently there is a single supported role: **Deployer**. The deployer role +allows for programatically triggering deployments. + +When new Encore Platform functionality is provided, we will add it to existing roles where applicable. +That means a role is not restricted to only access of APIs that existed at the time the client was initially authorized — a role will contain additional access where it makes sense for new or updated functionality. + +### Revoking an OAuth client +Open the OAuth clients page of the application settings page. + +Find the OAuth client that you want to delete and select Revoke. + +Select Revoke OAuth client to confirm you want to revoke the OAuth client. + +When you revoke an OAuth client, any active API access tokens that were created by the client are also revoked. + +### Encore Platform OAuth token endpoint +The Encore Platform's OAuth token endpoint is https://api.encore.dev/api/oauth/token. +See the [Platform API Reference](/docs/platform/api-reference) documentation for more information. + +Make requests to the OAuth token endpoint when you need an API access token. The OAuth token endpoint accepts requests that conform to the OAuth 2.0 client credentials grant request format, and returns responses that conform to the OAuth 2.0 client credentials grant response format. + +## OAuth client libraries +Popular programming languages provide OAuth client libraries to simplify your use of OAuth clients. + +For example, the following Go code shows how to create an OAuth client object that uses your client ID and client secret to generate an API access token for calls to the Encore Platform API. +Similar libraries exist for other popular programming languages. + +```go +package main + +import ( + "context" + "os" + + "golang.org/x/oauth2/clientcredentials" +) + +func main() { + oauthConfig := &clientcredentials.Config{ + ClientID: os.Getenv("OAUTH_CLIENT_ID"), + ClientSecret: os.Getenv("OAUTH_CLIENT_SECRET"), + TokenURL: "https://api.encore.dev/api/oauth/token", + } + + client := oauthConfig.Client(context.Background()) + + // Make API calls using `client.Get` etc. + resp, err := client.Get("https://api.encore.dev.com/api/...") + // ... +} +``` + +The example requires that you define environment variables `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET`, with their values set to the client ID and client secret that are created when you set up an OAuth client. + +### Verifying you can generate API access tokens +After you set up an OAuth client, an easy way to confirm that you can generate API access tokens is to make a curl request to the Encore Platform OAuth token endpoint. + + +```bash +curl -d "client_id=${OAUTH_CLIENT_ID}" -d "client_secret=${OAUTH_CLIENT_SECRET}" \ + -d "grant_type=client_credentials" "https://api.encore.dev/api/oauth/token" +``` + +The example requires that you define environment variables OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET, with their values set to your client ID and client secret. + +Here's an example response showing the API access token: + +```json +{"access_token":"MTcyODQ3NTg3NXww...GDxfmxnuq9zDEAmHmP5D44=","token_type":"Bearer","expires_in":3600, "actor": "o2c_my_key_id"} +``` + +## Limitations + +An OAuth access token expires after 1 hour — this duration cannot be modified.