---
title: "Authorize deployment"
method: POST
path: "/v2/deployments.authorizeDeployment"
tags: ["deployments"]
---

# Authorize deployment

`POST /v2/deployments.authorizeDeployment`

## Request

- Base URL: `https://api.unkey.com`
- URL: `https://api.unkey.com/v2/deployments.authorizeDeployment`
- Auth: HTTP bearer

Authorize a deployment that is awaiting approval. Deployments from forked
pull requests run code from outside your repository, so they wait for a
project member to approve them before they build.

The deployment must have the status `awaiting_approval`. Authorization is
asynchronous: this endpoint only enqueues it and returns immediately. The
deployment then moves to `pending` and starts its build. Poll
`getDeployment` to follow its status. If the build cannot start, the
deployment returns to `awaiting_approval`.

**Required Permissions**

Your root key must have the following permission:
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/<deployment_id>#write`

## Request body

- V2DeploymentsAuthorizeDeploymentRequestBody
  - `deploymentId` string, required: Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

## Response `202`

Authorization accepted and enqueued. The deployment moves to `pending`
and builds asynchronously; poll `getDeployment` to observe its status.

- V2DeploymentsAuthorizeDeploymentResponseBody: Authorize a deployment that is awaiting approval.
  - `meta` Meta, required: Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required: A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` EmptyResponse, required: Empty response object by design. A successful response indicates this operation was successfully executed.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden - Your root key can read the deployment but lacks the required permission.
- `404`: Not Found - The deployment does not exist in your workspace, or your root key cannot read it. Both cases return the same response, so deployment existence is never revealed. A root key that can read the deployment but lacks the required permission receives 403 instead.
- `412`: Precondition failed - The deployment is not awaiting approval, or the workspace has no Compute plan or is paused at its spend limit.
- `429`: Too Many Requests
- `500`: Internal server error

## Changes

- **2026-10-27** `6ed4b9847395`: 1 info
  - added the non-success response with the status `403`
- **2026-10-19** `727332f8849c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/deployments.authorizeDeployment/post.md)

---

[API](https://skmtc.dev/unkeyed/apis/unkey-api.md) - [All operations](https://skmtc.dev/unkeyed/apis/unkey-api/llms.txt) - [OpenAPI document](https://skmtc.dev/unkeyed/apis/unkey-api/revisions/6fbaa27f19e0?raw)