> This page is for Gateway. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Create Credential POST https://api-gateway.merge.dev/v1/credentials Content-Type: application/json Add your own API key for a vendor (BYOK). The gateway calls the vendor with it as your organization's key usage settings decide. An organization has one credential per vendor, so a second one is a 409. The key isn't tested on save: send a request to a model on that vendor to check it. Needs a Pro or Enterprise plan. Reference: https://docs.merge.dev/merge-gateway/management-api/credentials/create-credential ## Authentication - `Authorization` header (bearer token, required) — A management key (`mgmt_...`), sent as `Authorization: Bearer `. Reading /v1/routing-policies also accepts the organization's gateway API keys; writing there needs a management key. ## Request ### Body (application/json) This endpoint expects a CredentialV1Create. - `vendor` (string, required) — The vendor's slug, like `openai`. Can't change after creation: delete the credential and create a new one to switch vendors. An organization has at most one credential per vendor. - `api_base` (string, optional, nullable) — A custom base URL for the vendor's API, such as your own proxy. - `api_key` (string, optional, nullable) — The vendor API key. Required except for `vertexai` (uses config.service_account_json) and `bedrock` (can use AWS keys or a role in config instead). Never returned. - `config` (CredentialConfigV1Request, optional, nullable) — Vendor-specific settings, such as the Bedrock region or the Vertex AI project. - `fallback_to_managed` (boolean, optional, default: true) — When a request with this key fails, retry it once on Merge-managed access for the same vendor, if the organization has it. - `name` (string, optional, nullable) — A name for the credential, shown in the dashboard. ## Response ### 201 The created credential - `api_base` (string, required, nullable) — A custom base URL for the vendor's API, such as your own proxy. - `config` (CredentialConfigV1, required) — The non-secret vendor settings. Settings that aren't set are null. - `created_at` (datetime, required, nullable) — When the credential was created. - `credential_hint` (string, required, nullable) — The last 4 characters of the stored API key, like `a1b2`, to tell keys apart. null when the credential has no API key, or the key is under 12 characters (4 would give away too much of it). - `fallback_to_managed` (boolean, required) — When a request with this key fails, retry it once on Merge-managed access for the same vendor, if the organization has it. - `id` (string, required) — The credential's id. - `name` (string, required, nullable) — A name for the credential, shown in the dashboard. - `updated_at` (datetime, required, nullable) — When the credential last changed. - `vendor` (string, required) — The vendor's slug, like `openai`. Can't change after creation: delete the credential and create a new one to switch vendors. An organization has at most one credential per vendor. ## Errors ### 400 Bad Request Error The credential is invalid: the vendor doesn't allow BYOK, a required secret is missing, a config value is malformed, or api_base is not allowed. - `detail` (ErrorResponseDetail, required) — A message, or an object with a `code` to branch on and a `message`. ### 401 Unauthorized Error The key is missing or invalid. - `detail` (ErrorResponseDetail, required) — A message, or an object with a `code` to branch on and a `message`. ### 403 Forbidden Error The key lacks the scope this route needs, or the change is not allowed. - `detail` (ErrorResponseDetail, required) — A message, or an object with a `code` to branch on and a `message`. ### 409 Conflict Error The request conflicts with the current state. - `detail` (ErrorResponseDetail, required) — A message, or an object with a `code` to branch on and a `message`. ### 422 Unprocessable Entity Error Validation Error - `detail` (list of ValidationError, optional) ### 503 Service Unavailable Error A service the request needs, such as billing or the gateway itself, is temporarily unavailable. Retry later. - `detail` (ErrorResponseDetail, required) — A message, or an object with a `code` to branch on and a `message`. ## Types ### CredentialConfigV1Request Vendor-specific settings, including secrets. Only the fields sent change; a field can't be cleared once set. - `api_version` (string, optional, nullable) — Azure OpenAI API version. - `aws_access_key_id` (string, optional, nullable) — Bedrock access key id. - `aws_region` (string, optional, nullable) — Bedrock region, like `us-east-1`. - `aws_role_arn` (string, optional, nullable) — Bedrock IAM role to assume. - `aws_secret_access_key` (string, optional, nullable) — Bedrock secret access key, sent with aws_access_key_id. Never returned. - `azure_deployment` (string, optional, nullable) — Azure OpenAI deployment name. - `service_account_json` (string, optional, nullable) — Vertex AI service account key file, as a JSON string. Never returned. - `vertex_location` (string, optional, nullable) — Vertex AI location. - `vertex_project` (string, optional, nullable) — Vertex AI project id. ### CredentialConfigV1 Vendor-specific settings. Each field applies to the vendors named in it. - `api_version` (string, optional, nullable) — Azure OpenAI API version. - `aws_access_key_id` (string, optional, nullable) — Bedrock access key id. - `aws_region` (string, optional, nullable) — Bedrock region, like `us-east-1`. - `aws_role_arn` (string, optional, nullable) — Bedrock IAM role to assume. - `azure_deployment` (string, optional, nullable) — Azure OpenAI deployment name. - `vertex_location` (string, optional, nullable) — Vertex AI location. - `vertex_project` (string, optional, nullable) — Vertex AI project id. ### ErrorResponseDetail A message, or an object with a `code` to branch on and a `message`. ### ValidationError - `loc` (list of ValidationErrorLocItems, required) - `msg` (string, required) - `type` (string, required) - `ctx` (ValidationErrorCtx, optional) - `input` (any, optional) ### ErrorDetail A structured error. Some carry extra fields, like `count`. - `code` (string, required) — A stable code to branch on, like `payment_method_required`. - `message` (string, required) — A human-readable explanation. ### ValidationErrorLocItems ### ValidationErrorCtx ## Examples **Request** ```json { "vendor": "bedrock", "config": { "aws_region": "us-east-1", "aws_role_arn": "arn:aws:iam::123456789012:role/merge-gateway-bedrock" }, "fallback_to_managed": true, "name": "bedrock-prod" } ``` **Response** ```json { "api_base": null, "config": { "api_version": null, "aws_access_key_id": null, "aws_region": "us-east-1", "aws_role_arn": "arn:aws:iam::123456789012:role/merge-gateway-bedrock", "azure_deployment": null, "vertex_location": null, "vertex_project": null }, "created_at": "2026-06-02T17:04:00Z", "credential_hint": null, "fallback_to_managed": true, "id": "6d2a9f4c-3b1e-4d7a-8c5f-9e0b2a4c6d81", "name": "bedrock-prod", "updated_at": "2026-09-14T09:30:00Z", "vendor": "bedrock" } ``` **SDK Code** ```python import requests url = "https://api-gateway.merge.dev/v1/credentials" payload = { "vendor": "bedrock", "config": { "aws_region": "us-east-1", "aws_role_arn": "arn:aws:iam::123456789012:role/merge-gateway-bedrock" }, "fallback_to_managed": True, "name": "bedrock-prod" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api-gateway.merge.dev/v1/credentials'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"vendor":"bedrock","config":{"aws_region":"us-east-1","aws_role_arn":"arn:aws:iam::123456789012:role/merge-gateway-bedrock"},"fallback_to_managed":true,"name":"bedrock-prod"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api-gateway.merge.dev/v1/credentials" payload := strings.NewReader("{\n \"vendor\": \"bedrock\",\n \"config\": {\n \"aws_region\": \"us-east-1\",\n \"aws_role_arn\": \"arn:aws:iam::123456789012:role/merge-gateway-bedrock\"\n },\n \"fallback_to_managed\": true,\n \"name\": \"bedrock-prod\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api-gateway.merge.dev/v1/credentials") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"vendor\": \"bedrock\",\n \"config\": {\n \"aws_region\": \"us-east-1\",\n \"aws_role_arn\": \"arn:aws:iam::123456789012:role/merge-gateway-bedrock\"\n },\n \"fallback_to_managed\": true,\n \"name\": \"bedrock-prod\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api-gateway.merge.dev/v1/credentials") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"vendor\": \"bedrock\",\n \"config\": {\n \"aws_region\": \"us-east-1\",\n \"aws_role_arn\": \"arn:aws:iam::123456789012:role/merge-gateway-bedrock\"\n },\n \"fallback_to_managed\": true,\n \"name\": \"bedrock-prod\"\n}") .asString(); ``` ```php request('POST', 'https://api-gateway.merge.dev/v1/credentials', [ 'body' => '{ "vendor": "bedrock", "config": { "aws_region": "us-east-1", "aws_role_arn": "arn:aws:iam::123456789012:role/merge-gateway-bedrock" }, "fallback_to_managed": true, "name": "bedrock-prod" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api-gateway.merge.dev/v1/credentials"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"vendor\": \"bedrock\",\n \"config\": {\n \"aws_region\": \"us-east-1\",\n \"aws_role_arn\": \"arn:aws:iam::123456789012:role/merge-gateway-bedrock\"\n },\n \"fallback_to_managed\": true,\n \"name\": \"bedrock-prod\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "vendor": "bedrock", "config": [ "aws_region": "us-east-1", "aws_role_arn": "arn:aws:iam::123456789012:role/merge-gateway-bedrock" ], "fallback_to_managed": true, "name": "bedrock-prod" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api-gateway.merge.dev/v1/credentials")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```