---
title: "Create credential"
method: POST
path: "/v1/credentials"
tags: ["Credentials"]
---

# Create credential

`POST /v1/credentials`

Creates a new credential for the current organization

## Headers

- `x-api-key` string, nullable — Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.

## Request body

- CreateCredentialRequest — Request model for creating a new credential.
  - `name` string, required — Name of the credential
  - `credential_type` 'password' | 'credit_card' | 'secret', required — Type of credential stored in the system.
  - `credential` union, required — The credential data to store
    - NonEmptyPasswordCredential — Password credential model that requires non-empty values.
      - `password` string, required — The password value (must not be empty)
      - `username` string, required — The username associated with the credential (must not be empty)
      - `totp` string, nullable — Optional TOTP (Time-based One-Time Password) string used to generate 2FA codes
      - `totp_type` 'authenticator' | 'email' | 'text' | 'passkey' | 'none' — Type of 2FA/TOTP method used.
      - `totp_identifier` string, nullable — Identifier (email or phone number) used to fetch TOTP codes
      - `metadata` object, nullable — Optional additional password credential metadata fields
    - NonEmptyCreditCardCredential — Credit card credential model that requires non-empty values.
      - `card_number` string, required — The full credit card number (must not be empty)
      - `card_cvv` string, required — The card's CVV (must not be empty)
      - `card_exp_month` string, required — The card's expiration month (must not be empty)
      - `card_exp_year` string, required — The card's expiration year (must not be empty)
      - `card_brand` string, required — The card's brand (must not be empty)
      - `card_holder_name` string, required — The name of the card holder (must not be empty)
      - `billing_address` CreditCardBillingAddress — Optional billing address fields associated with a credit card credential.
        - `line1` string, nullable — Billing address line 1
        - `line2` string, nullable — Billing address line 2
        - `city` string, nullable — Billing city
        - `state` string, nullable — Billing state or region
        - `state_code` string, nullable — Billing state or region code
        - `postal_code` string, nullable — Billing postal code
        - `country` string, nullable — Billing country
        - `country_code` string, nullable — ISO 3166-1 alpha-2 billing country code
      - `billing_email` string, nullable — Optional billing email address
      - `billing_phone` string, nullable — Optional billing phone number
      - `metadata` object, nullable — Optional additional credit card metadata fields
    - SecretCredential — Generic secret credential.
      - `secret_value` string, required — The secret value
      - `secret_label` string, nullable — Optional label describing the secret
  - `vault_type` 'skyvern' | 'bitwarden' | 'azure_vault' | 'gcp' | 'custom'
  - `proxy_location` union — Optional proxy location for this credential's pinned proxy identity.
    - 'RESIDENTIAL' | 'US-CA' | 'US-NY' | 'US-TX' | 'US-FL' | 'US-WA' | 'RESIDENTIAL_ES' | 'RESIDENTIAL_IE' | 'RESIDENTIAL_GB' | 'RESIDENTIAL_IN' | 'RESIDENTIAL_JP' | 'RESIDENTIAL_FR' | 'RESIDENTIAL_DE' | 'RESIDENTIAL_NZ' | 'RESIDENTIAL_ZA' | 'RESIDENTIAL_AR' | 'RESIDENTIAL_AU' | 'RESIDENTIAL_BR' | 'RESIDENTIAL_TR' | 'RESIDENTIAL_CA' | 'RESIDENTIAL_MX' | 'RESIDENTIAL_IT' | 'RESIDENTIAL_NL' | 'RESIDENTIAL_PH' | 'RESIDENTIAL_KR' | 'RESIDENTIAL_SA' | 'RESIDENTIAL_ISP' | 'NONE'
    - GeoTarget — Granular proxy geo-targeting request with country, optional subdivision, and optional city.
      - `country` string, required — ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE')
      - `subdivision` string, nullable — ISO 3166-2 subdivision code without country prefix (e.g., 'CA' for California, 'NY' for New York)
      - `city` string, nullable — City name in English from GeoNames (e.g., 'New York', 'Los Angeles', 'London')
    - object
  - `proxy_session_id` string, nullable — Optional advanced reuse key for this credential's pinned proxy identity.
  - `rotate_proxy_session_id` boolean — Rotate the Skyvern-managed proxy sticky-session id when updating this credential.
  - `browser_profile_id` string, nullable — Optional plain browser profile to link as this credential's saved profile. Must be an unmanaged profile in your organization that no other credential already owns.
  - `auto_profile_disabled` boolean — Disable automatic saving and reuse of this credential's browser profile.
  - `pin_saved_session_ip` boolean — Keep the same IP across sign-ins that reuse this credential's saved profile.
  - `tested_url` string, nullable — Login page URL used during the credential test

## Response `201`

Successful Response

- CredentialResponse — Response model for credential operations.
  - `credential_id` string, required — Unique identifier for the credential
  - `credential` union, required — The credential data
    - PasswordCredentialResponse — Response model for password credentials — non-sensitive fields only. SECURITY: Must NEVER include password or TOTP secret.
      - `username` string, required — The username associated with the credential
      - `totp_type` 'authenticator' | 'email' | 'text' | 'passkey' | 'none' — Type of 2FA/TOTP method used.
      - `totp_identifier` string, nullable — Identifier (email or phone number) used to fetch TOTP codes
    - CreditCardCredentialResponse — Response model for credit card credentials — non-sensitive fields only. SECURITY: Must NEVER include full card number, CVV, expiration date, card holder name, billing fields, or metadata.
      - `last_four` string, required — Last four digits of the credit card number
      - `brand` string, required — Brand of the credit card
    - SecretCredentialResponse — Response model for secret credentials — non-sensitive fields only. SECURITY: Must NEVER include the secret_value.
      - `secret_label` string, nullable — Optional label for the stored secret
  - `credential_type` 'password' | 'credit_card' | 'secret', required — Type of credential stored in the system.
  - `name` string, required — Name of the credential
  - `vault_type` 'skyvern' | 'bitwarden' | 'azure_vault' | 'gcp' | 'custom'
  - `browser_profile_id` string, nullable — Browser profile ID linked to this credential
  - `auto_profile_disabled` boolean, nullable — Whether automatic saving and reuse of this credential's browser profile is disabled.
  - `pin_saved_session_ip` boolean — Whether sign-ins reusing this credential's saved profile keep the same IP
  - `tested_url` string, nullable — Login page URL used during the credential test
  - `user_context` string, nullable — User-provided context describing the login sequence (e.g., 'click SSO button first')
  - `save_browser_session_intent` boolean, nullable — Whether the user intends to save a browser session, regardless of test outcome
  - `run_sequentially` boolean
  - `folder_id` string, nullable — ID of the credential folder this credential belongs to, if any
  - `proxy_location` union — Optional proxy location used for the credential's pinned proxy identity.
    - 'RESIDENTIAL' | 'US-CA' | 'US-NY' | 'US-TX' | 'US-FL' | 'US-WA' | 'RESIDENTIAL_ES' | 'RESIDENTIAL_IE' | 'RESIDENTIAL_GB' | 'RESIDENTIAL_IN' | 'RESIDENTIAL_JP' | 'RESIDENTIAL_FR' | 'RESIDENTIAL_DE' | 'RESIDENTIAL_NZ' | 'RESIDENTIAL_ZA' | 'RESIDENTIAL_AR' | 'RESIDENTIAL_AU' | 'RESIDENTIAL_BR' | 'RESIDENTIAL_TR' | 'RESIDENTIAL_CA' | 'RESIDENTIAL_MX' | 'RESIDENTIAL_IT' | 'RESIDENTIAL_NL' | 'RESIDENTIAL_PH' | 'RESIDENTIAL_KR' | 'RESIDENTIAL_SA' | 'RESIDENTIAL_ISP' | 'NONE'
    - GeoTarget — Granular proxy geo-targeting request with country, optional subdivision, and optional city.
      - `country` string, required — ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE')
      - `subdivision` string, nullable — ISO 3166-2 subdivision code without country prefix (e.g., 'CA' for California, 'NY' for New York)
      - `city` string, nullable — City name in English from GeoNames (e.g., 'New York', 'Los Angeles', 'London')
    - object
  - `proxy_session_id` string, nullable — Opaque Skyvern-managed proxy sticky-session id.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/skyvern-ai/apis/skyvern-api-2.md) · [All operations](https://skmtc.net/skyvern-ai/apis/skyvern-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/skyvern-ai/skyvern-api-2/versions/29562c6e0364/schema)