{"templateId":"markdown","versions":[{"version":"2.0","label":"v2.0","link":"/percents-api/auth-security/authentication","default":true,"active":true,"folderId":"27d36c3a"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Authentication","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"authentication","__idx":0},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API uses issuer server-side API tokens and source IP allowlisting. Use the API-token header shown in these docs and in the API reference."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"network-access","__idx":1},"children":["Network Access"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Percents API is behind a firewall that allowlists inbound source IPs. To access the API, the issuer must provide the source IP addresses or CIDR ranges that will call Percents from issuer-controlled infrastructure."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep the allowlist aligned with production and sandbox egress changes. Requests from unregistered source IPs should be expected to fail before API-token authentication is evaluated."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-tokens","__idx":2},"children":["API Tokens"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the token in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"Authorization: token <tok_id>:<api_secret>\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"Authorization: token tok_11111111-1111-4111-8111-111111111111:api_test_secret\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tok_"]}," value identifies the token. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api_"]}," prefix may appear in token-management ids where relevant to the integration or support workflow. Treat the token secret as confidential and never place it in client-side applications."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sdk-request-routing","__idx":3},"children":["SDK Request Routing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK does not use an issuer API token in the browser. It uses a customer-side proxy and a short-lived token restricted to one cardholder group. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/auth-security/sdk-auth"},"children":["SDK Authentication"]}," for the session and production-authentication model."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The issuer API-token scheme on this page remains for issuer server-to-server API calls. Do not use those credentials in the SDK, iframe, or a browser-accessible proxy response."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"failure-modes","__idx":4},"children":["Failure Modes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authentication and authorization failures use the standard public error response:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"uuid\": \"err_aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\n  \"code\": 401001,\n  \"httpStatusCode\": 401,\n  \"message\": \"Unauthorized\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uuid"]}," when contacting Percents support. Do not branch production behavior on the human-readable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]},"."]}]},"headings":[{"value":"Authentication","id":"authentication","depth":1},{"value":"Network Access","id":"network-access","depth":2},{"value":"API Tokens","id":"api-tokens","depth":2},{"value":"SDK Request Routing","id":"sdk-request-routing","depth":2},{"value":"Failure Modes","id":"failure-modes","depth":2}],"frontmatter":{"seo":{"title":"Authentication"}},"lastModified":"2026-07-21T18:22:26.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/percents-api/auth-security/authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}