{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Authentication"},"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":["All requests to the iClosed.io API must include a valid API key. This page covers how authentication works, how to manage your keys, and how to keep them secure."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$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":"Detail"},"children":["Detail"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Method"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bearer token in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token format"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Must start with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iclosed_"]}," prefix"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Scope"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keys are tied to a user and account — requests run in that context"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transport"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HTTPS only"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"header-format","__idx":2},"children":["Header Format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Include this header on every request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Authorization: Bearer iclosed_<your-api-key>\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bearer"]}," (capitalised, with a space) and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iclosed_"]}," prefix are required. No other authentication method is supported."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"obtaining-an-api-key","__idx":3},"children":["Obtaining an API Key"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log in at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://app.iclosed.io"},"children":["app.iclosed.io"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settings → Developer → API Keys"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create API Key"]},", give it a name, and set an optional expiration date"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Copy the key immediately — it will not be shown again after you leave the page"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store it in an environment variable or secrets manager (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#security-best-practices"},"children":["Security best practices"]},")"]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API access requires a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Business or Enterprise"]}," plan. If you do not see an API Keys section, check your plan at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://iclosed.io/pricing"},"children":["iclosed.io/pricing"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"key-lifecycle","__idx":4},"children":["Key Lifecycle"]},{"$$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":"State"},"children":["State"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"API behaviour"},"children":["API behaviour"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Active"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Requests succeed normally"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Expired"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"message\": \"API key expired\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Revoked"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"message\": \"Invalid API key\""]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rotating a key:"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a new key in Settings"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update your integration to use the new key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Revoke or delete the old key"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"code-examples","__idx":5},"children":["Code Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"curl","__idx":6},"children":["cURL"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://public.api.iclosed.io/v1/eventCalls?eventType=UPCOMING\" \\\n  -H \"Authorization: Bearer iclosed_YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"javascript-fetch","__idx":7},"children":["JavaScript (fetch)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const response = await fetch('https://public.api.iclosed.io/v1/contacts', {\n  method: 'POST',\n  headers: {\n    'Authorization': 'Bearer iclosed_YOUR_API_KEY',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify({\n    firstName: 'Jane',\n    lastName: 'Doe',\n    email: 'jane@example.com'\n  })\n});\n\nconst { data } = await response.json();\nconsole.log(data.contact.id);\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"python","__idx":8},"children":["Python"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import requests\n\nresponse = requests.get(\n    'https://public.api.iclosed.io/v1/eventCalls',\n    params={'eventType': 'UPCOMING', 'limit': 20},\n    headers={\n        'Authorization': 'Bearer iclosed_YOUR_API_KEY',\n        'Content-Type': 'application/json'\n    }\n)\n\ndata = response.json()\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"postman","__idx":9},"children":["Postman"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open your request → ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authorization"]}," tab"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bearer Token"]}," from the Type dropdown"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Paste your full key including the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iclosed_"]}," prefix"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication-error-responses","__idx":10},"children":["Authentication Error Responses"]},{"$$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":"HTTP Code"},"children":["HTTP Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"message value"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"code value"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause"},"children":["Cause"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"API key is required\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MISSING_API_KEY"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header missing or token does not start with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iclosed_"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"Invalid API key\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Key is unknown, revoked, or malformed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"API key expired\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Key has passed its expiration date"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"Forbidden\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Key exists but lacks permission for this resource"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example 401 response body:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"message\": \"API key is required\",\n  \"code\": \"MISSING_API_KEY\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"security-best-practices","__idx":11},"children":["Security Best Practices"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Never commit keys to version control."]}," Use environment variables, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]}," files (git-ignored), or a secrets manager."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["One key per environment."]}," Create separate keys for production and development so you can revoke each independently."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["One key per integration."]}," If iClosed connects to multiple tools, give each its own key."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Set expiration dates."]}," Short-lived keys reduce exposure if a key leaks."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rotate after any suspected exposure."]}," Revoke the compromised key immediately and issue a new one."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTPS only."]}," Never send requests over plain HTTP."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"oauth-vs-api-keys","__idx":12},"children":["OAuth vs API keys"]},{"$$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":"Method"},"children":["Method"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Best for"},"children":["Best for"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server-to-server integrations for a single workspace you control"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OAuth client"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Third-party apps where each customer signs in and grants access to their own workspace"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To register an OAuth client and implement the authorization code flow, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/oauth-clients"},"children":["OAuth Clients"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"see-also","__idx":13},"children":["See Also"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/oauth-clients"},"children":["OAuth Clients"]}," — Register clients, user consent, tokens, and approval"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/rate-limiting"},"children":["Rate Limiting"]}," — Request limits and backoff strategy"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/errors"},"children":["Errors"]}," — Full error code reference"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://api-docs-iclosed.redocly.app/openapi/v1/openapi"},"children":["API Reference"]}," — All endpoints"]}]}]},"headings":[{"value":"Authentication","id":"authentication","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Header Format","id":"header-format","depth":2},{"value":"Obtaining an API Key","id":"obtaining-an-api-key","depth":2},{"value":"Key Lifecycle","id":"key-lifecycle","depth":2},{"value":"Code Examples","id":"code-examples","depth":2},{"value":"cURL","id":"curl","depth":3},{"value":"JavaScript (fetch)","id":"javascript-fetch","depth":3},{"value":"Python","id":"python","depth":3},{"value":"Postman","id":"postman","depth":3},{"value":"Authentication Error Responses","id":"authentication-error-responses","depth":2},{"value":"Security Best Practices","id":"security-best-practices","depth":2},{"value":"OAuth vs API keys","id":"oauth-vs-api-keys","depth":2},{"value":"See Also","id":"see-also","depth":2}],"frontmatter":{"seo":{"title":"Authentication"}},"lastModified":"2026-09-02T09:59:33.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}