{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"API Keys & 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":"api-keys--authentication","__idx":0},"children":["API Keys & Authentication"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API keys authenticate your requests to the Clearspeed Integration API. Keys are scoped to a specific questionnaire and carry explicit permissions — so a key created for one questionnaire cannot access another, and a key without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participant:write"]}," permission cannot create participants."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page covers:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#how-authentication-works"},"children":["How authentication works"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#available-scopes"},"children":["Available scopes"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#creating-your-first-api-key-from-the-web-app"},"children":["Creating your first API key from the web app"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#managing-api-keys-via-api"},"children":["Managing API keys via API"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-authentication-works","__idx":2},"children":["How Authentication Works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every API request must include your API key in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"Authorization: <your-api-key>\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The key is validated against the questionnaire specified in the request (via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["project_uuid"]}," or the URL path). A key issued for questionnaire A will be rejected for questionnaire B."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"available-scopes","__idx":3},"children":["Available Scopes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When creating an API key you choose which actions it may perform. Each key can have one or more of the following scopes:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scope"},"children":["Scope"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Allows"},"children":["Allows"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participant:read"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read participant records"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participant:write"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create participants and initiate retakes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participant:delete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delete participant records"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apikey:write"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create new API keys for the same questionnaire"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apikey:delete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delete API keys for the same questionnaire"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Principle of least privilege"]}," — only grant the scopes your integration actually needs. A key used only for creating participants needs ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participant:write"]}," and nothing else."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"creating-your-first-api-key-from-the-web-app","__idx":4},"children":["Creating Your First API Key from the Web App"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your first API key for a questionnaire must be created through the Clearspeed web application. You need an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Admin"]}," role on the questionnaire or tenant to do this."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-1--open-the-integration-page","__idx":5},"children":["Step 1 — Open the Integration page"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Navigate to the questionnaire you want to integrate with. In the questionnaire-specific left navigation bar, click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Integration"]},". The right panel shows an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API Keys"]}," section at the top with an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["+ Add API Key"]}," button."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/apikeys-step1-integration-page.56750c87b83a3c32a7f9dfb6e57923e1afe304de557507e76325aa2959fd4db3.9c1bb791.png","alt":"Integration page showing the API Keys section with the Add API Key button"},"children":[]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Screenshot placeholder — Integration page, API Keys section"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2--create-a-new-api-key","__idx":6},"children":["Step 2 — Create a new API key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["+ Add API Key"]},", enter a descriptive name (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production-participant-writer"]},"), and select the scopes your integration requires."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/apikeys-step2-create-dialog.9c72ef05cb653ea12782db284d086f794bfccc0745d2de2bc6e43008445dba51.9c1bb791.png","alt":"Create API Key dialog with key name field and scope checkboxes"},"children":[]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Screenshot placeholder — Create API Key dialog"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-3--copy-the-key-immediately","__idx":7},"children":["Step 3 — Copy the key immediately"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The full API key value is shown ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["only once"]}," at creation time. Copy it now and store it securely (for example, in your secrets manager). After you close this dialog, only a masked version of the key is shown."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/apikeys-step3-copy-key.0f0be3c29d06a0245b5be9557fb56b78901aa2f76899f32f51bc2836429d1d2a.9c1bb791.png","alt":"API key created successfully modal showing the full key value"},"children":[]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Screenshot placeholder — key created modal with copy button"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-4--confirm-the-key-appears-in-the-list","__idx":8},"children":["Step 4 — Confirm the key appears in the list"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After closing the dialog you will see the new key listed in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API Keys"]}," section on the Integration page, showing its name, scopes, and a masked key value. You can create additional keys or delete existing ones from this list at any time."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/apikeys-step4-keys-list.486f426be4192910cc28749187b419cc5e13dc3831782f2edb3834220b2ca22a.9c1bb791.png","alt":"API Keys section on the Integration page showing the newly created key"},"children":[]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Screenshot placeholder — Integration page, API Keys list with new key visible"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"managing-api-keys-via-api","__idx":9},"children":["Managing API Keys via API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have a key with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apikey:write"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apikey:delete"]}," scope, you can create, list, and delete keys programmatically — useful for key rotation and automation workflows."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/public/integration-api"},"children":["Integration API reference"]}," for the full endpoint details, request/response schemas, and examples."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"key-rotation-best-practice","__idx":10},"children":["Key Rotation Best Practice"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a new key with the same scopes as the one being rotated."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update your integration to use the new key."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify your integration is working."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Delete the old key."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This zero-downtime approach ensures your integration is never without a valid key during rotation."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"required-scopes-per-operation","__idx":11},"children":["Required Scopes per Operation"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Operation"},"children":["Operation"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required scope"},"children":["Required scope"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create participant"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participant:write"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retake questionnaire"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participant:write"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Update participant outcome"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participant:write"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create API key"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apikey:write"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List API keys"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apikey:write"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apikey:delete"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delete API key"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apikey:delete"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"receiving-webhook-results","__idx":12},"children":["Receiving Webhook Results"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Clearspeed sends result payloads to a webhook URL you configure per questionnaire. Your endpoint can be protected with either an API key or OAuth2 client credentials — Clearspeed will authenticate to your endpoint using whichever method you choose. See the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/webhooks"},"children":["Webhook Configuration guide"]}," for full setup instructions and the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/public/integration-api"},"children":["Integration API reference"]}," for the payload schema."]}]},"headings":[{"value":"API Keys & Authentication","id":"api-keys--authentication","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"How Authentication Works","id":"how-authentication-works","depth":2},{"value":"Available Scopes","id":"available-scopes","depth":2},{"value":"Creating Your First API Key from the Web App","id":"creating-your-first-api-key-from-the-web-app","depth":2},{"value":"Step 1 — Open the Integration page","id":"step-1--open-the-integration-page","depth":3},{"value":"Step 2 — Create a new API key","id":"step-2--create-a-new-api-key","depth":3},{"value":"Step 3 — Copy the key immediately","id":"step-3--copy-the-key-immediately","depth":3},{"value":"Step 4 — Confirm the key appears in the list","id":"step-4--confirm-the-key-appears-in-the-list","depth":3},{"value":"Managing API Keys via API","id":"managing-api-keys-via-api","depth":2},{"value":"Key Rotation Best Practice","id":"key-rotation-best-practice","depth":2},{"value":"Required Scopes per Operation","id":"required-scopes-per-operation","depth":2},{"value":"Receiving Webhook Results","id":"receiving-webhook-results","depth":2}],"frontmatter":{"title":"API Keys & Authentication","description":"How to create and manage questionnaire-level API keys, understand scopes, and authenticate API requests.","seo":{"title":"API Keys & Authentication"}},"lastModified":"2026-04-10T07:52:18.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/api-keys","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}