---
title: "Create a BYOK credential"
method: POST
path: "/ai-gateway/byok-credentials"
tags: ["ai-gateway"]
---

# Create a BYOK credential

`POST /ai-gateway/byok-credentials`

## Request

- Base URL: `https://api.vercel.com`
- URL: `https://api.vercel.com/ai-gateway/byok-credentials`
- Auth: HTTP bearer

Create a new BYOK credential

## Query parameters

- `teamId` string
- `slug` string

## Request body

- object
  - `ownerId` string: The owner ID for this credential. Ignored for customer tokens, which always create in their own team.
  - `providerSlug` string, required: The provider slug this credential is for (e.g., "openai", "anthropic")
  - `name` string, required: The developer-entered name for this credential
  - `active` boolean: Whether the credential is active and can be used
  - `zeroDataRetention` boolean: Whether the customer attested this external credential has a zero data retention policy
  - `userId` string: The ID of the user performing this action, used for Activity-log attribution.
  - `mappings` object[]: Model mappings to create atomically with the credential (e.g. Azure deployments). One DynamoDB transaction holds the credential plus all mappings, so at most 99 mappings fit.
    - `gatewayModelSlug` string, required: The AI Gateway model slug (e.g., "openai/gpt-5.4")
    - `customModelId` string, required: The customer's custom model ID (e.g., "my-finetuned-gpt-5")

## Response `201`

- object
  - `active` false | true, required
  - `createdAt` number, required
  - `credentialId` string, required
  - `lastFourChars` string, required
  - `name` string, required
  - `ownerId` string, required
  - `providerSlug` string, required
  - `rotatedAt` number, nullable, required
  - `updatedAt` number, required
  - `zeroDataRetention` false | true, required

## Other responses

- `400`: One of the provided values in the request body is invalid.
- `401`: The request is not authorized.
- `403`: You do not have permission to access this resource.
- `404`
- `410`
- `429`
- `500`

## Changes

- **2026-10-29** `4966aebe003c`: 1 info
  - added the required property `rotatedAt` to the response with the `201` status
- **2026-10-27** `ef8042371d97`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vercel/apis/vercel-api/changes/ai-gateway/byok-credentials/post.md)

---

[API](https://skmtc.dev/vercel/apis/vercel-api.md) - [All operations](https://skmtc.dev/vercel/apis/vercel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vercel/apis/vercel-api/revisions/60686c0e1f6a?raw)