Vortex
    • Overview
    • Vortex SDK
    • Quick Start With The SDK
    • Ramp Lifecycle
    • Ephemeral Key Custody
    • Authentication And Partner Keys
    • Sandbox
    • BRL / KYC notes
    • Production Checklist
    • Quotes
      • Quotes And Pricing
      • Get existing quote
        GET
      • Create a new quote
        POST
      • Create a quote for the best network
        POST
    • Vortex Widget
      • Widget parameters
      • Widget Integration
      • Generating widget URL (for existing quote)
        POST
      • Generating widget URL (for existing quote)
        POST
    • Ramp
      • Get ramp status
        GET
      • Get ramp history for wallet address
        GET
      • Register new ramp process
        POST
      • Update ramp process
        POST
      • Start ramp process
        POST
      • Get ramp error logs
        GET
    • Account Management
      • Brazil
        • Brazilian KYC Process Overview
        • Get status of the last ramp event for a user
        • Start KYC level 2 process for a user
      • Europe
        • Coming soon...
      • Get user's remaining transaction limits
        GET
      • Get KYC document upload URLs
        POST
      • Get user information
        GET
      • Create user or retry KYC
        POST
      • Submit KYC level 1 data
        POST
      • Get selfie liveness URL
        GET
      • Get user's KYC status
        GET
      • Validate Pix key
        GET
    • Webhooks
      • Overview
      • Webhooks
      • Register Webhook
      • Delete Webhook
    • Public Key
      • Overview
      • Public Key
    • Reference Data
      • Supported Payment Methods
      • Supported Cryptocurrencies
      • Supported Countries
      • Supported Fiat Currencies
    • Schemas
      • Schemas
      • StartKYC2Response
      • GetKycStatusResponse
      • ValidatePixKeyResponse
      • GetUserRemainingLimitResponse
      • TriggerOfframpRequest
      • TriggerOfframpResponse
      • BrlaAddress
      • TaxIdType
      • CreateSubaccountRequest
      • CreateSubaccountResponse
      • KYCDocType
      • KYCDataUploadFileFiles
      • StartKYC2Request
      • GetUserResponse
      • StartRampRequest
      • RampDirection
      • GetWidgetUrlLocked
      • CountryCode
      • PaymentMethod
      • SimpleStatus
      • FiatToken
      • OnChainToken
      • GetWidgetUrlRefresh
      • CreateBestQuoteRequest
      • GetRampHistoryTransaction
      • GetRampHistoryResponse
      • BrlaErrorResponse
      • RegisterRampRequest
      • AccountMeta
      • Networks
      • PaymentData
      • RampProcess
      • RampPhase
      • DestinationType
      • UnsignedTx
      • CleanupPhase
      • CreateQuoteRequest
      • QuoteResponse
      • RampCurrency
      • UpdateRampRequest
      • PresignedTx
      • ErrorResponse
      • RampErrorLog
      • GetRampErrorLogsResponse
      • BrlaValidatePixKeyResponse
      • BrlaGetSelfieLivenessUrlResponse
      • AveniaDocumentType
      • AveniaKYCDataUploadRequest
      • DocumentUploadEntry
      • AveniaKYCDataUploadResponse
      • KycLevel1Payload
      • KycLevel1Response

    Authentication And Partner Keys

    Vortex authenticates partners with two key types and accepts a third principal (Supabase Bearer) for first-party user flows.

    Public Keys#

    Public keys use the pk_live_* or pk_test_* prefix. They are used for partner attribution, tracking, and partner-specific quote behavior. Public keys may be included in SDK configuration, in request bodies as apiKey, or in the ?apiKey= query string.
    Public keys do not authenticate sensitive partner operations. An invalid or expired public key, however, is rejected with HTTP 401 on routes that validate it — it is not silently ignored.

    Secret Keys#

    Secret keys use the sk_live_* or sk_test_* prefix. They authenticate partner operations through the X-API-Key header.
    Secret keys must be treated as server-side credentials. Do not expose them in browser bundles, mobile app binaries, URLs, screenshots, analytics tools, logs, or support tickets.
    When a request includes partnerId (in quote creation), the API requires a matching secret key in X-API-Key. partnerId may be either the partner's UUID or its name; matching is performed by partner name. If the authenticated partner does not match the requested partner, Vortex rejects the request with HTTP 403.
    Ramp endpoints (/v1/ramp/register, /update, /start, GET /v1/ramp/{id}, history, errors) require authentication unconditionally — either an sk_* key OR a Supabase Bearer token. Anonymous requests are rejected with HTTP 401.
    Webhook endpoints require sk_* and do not accept Supabase Bearer tokens.

    Supabase Bearer tokens#

    Some endpoints — currently /v1/brla/* — accept only Supabase Bearer tokens, not sk_*. These are intended for first-party flows where the end user has authenticated with Vortex directly. Partner SDK integrations cannot drive BRL KYC through these endpoints with only sk_* / pk_*; the user must complete onboarding through the Vortex application or hosted widget first.

    Recommended Handling#

    Store secret keys in a secret manager or encrypted environment configuration. Rotate keys if they are exposed, no longer needed, or tied to a retired integration. Use test keys in sandbox and live keys only in production.
    Modified at 2026-05-16 09:38:15
    Previous
    Ephemeral Key Custody
    Next
    Sandbox
    Built with