Authentication

Every request to /api/v2 is authenticated. Pass an API token as a bearer token in the Authorization header. Archive validates it on every request. Every operation requires a token.

Authorization: Bearer <your-token>
WORKSPACE-ID: <workspace-uuid>

The scheme name is case-insensitive, so bearer works as well as Bearer.

The WORKSPACE-ID header is required only for workspace-scoped operations. See the Workspaces guide. The Authorization header is required on every request. Here is a complete request with both headers:

query WorkspaceDefault {
  workspace {
    id
    name
  }
}

Authorization: Bearer docs_demo_token_0000000000000000000000
WORKSPACE-ID: 6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a

curl https://app.archive.com/api/v2 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer docs_demo_token_0000000000000000000000' \
  -H 'WORKSPACE-ID: 6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a' \
  -d '{
  "query": "query WorkspaceDefault {\n  workspace {\n    id\n    name\n  }\n}"
}'

const response = await fetch("https://app.archive.com/api/v2", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer docs_demo_token_0000000000000000000000",
    "WORKSPACE-ID": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a"
  },
  body: JSON.stringify({
    query: `query WorkspaceDefault {
  workspace {
    id
    name
  }
}`
  })
})
console.log(JSON.stringify(await response.json(), null, 2))

require "json"
require "net/http"

query = <<~'GRAPHQL'
  query WorkspaceDefault {
    workspace {
      id
      name
    }
  }
GRAPHQL

response = Net::HTTP.post(
  URI("https://app.archive.com/api/v2"),
  { query: query }.to_json,
  "Content-Type" => "application/json",
  "Authorization" => "Bearer docs_demo_token_0000000000000000000000",
  "WORKSPACE-ID" => "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a"
)
puts response.body

import json
import requests

query = """
query WorkspaceDefault {
  workspace {
    id
    name
  }
}
"""

response = requests.post(
    "https://app.archive.com/api/v2",
    json={"query": query},
    headers={
        "Authorization": "Bearer docs_demo_token_0000000000000000000000",
        "WORKSPACE-ID": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
    },
)
print(json.dumps(response.json(), indent=2))

Creating a token

Create tokens from the Integration tab in the Archive app. You don’t need to contact support.

• If your workspace belongs to an organization, the token works across every workspace in the organization. Select the workspace per request with the WORKSPACE-ID header.
• Otherwise, the token is scoped to the single workspace it was issued for.

The full token is displayed only once, when you create it. Archive stores a hash and the last four characters. You can identify a token by those four characters later, but you can’t retrieve the full value again. Store it in a secret manager as soon as you create it.

Rotating and disabling tokens

Re-provisioning from the Integration tab rotates the token. The new token takes effect immediately, and the old one stops working. Rotate as soon as you suspect a token has been exposed. A rotated token fails with HTTP 401 and the body {"errors":"Missing or invalid authentication token"}. An unrecognized token gets the same response. Every 401 carries a WWW-Authenticate: Bearer header.

Pausing is separate from rotating. A paused token keeps its identity, but Archive refuses it with HTTP 401 and the body {"errors":"Account is disabled"}. If you rotate a paused token, the replacement is issued paused too. Re-enable it before use.

Token security

• Keep tokens server-side. Never ship a token to a browser, mobile app, or any other client you don’t control.
• Store tokens in environment variables or a secret manager, not in source control.
• Rotate tokens if you suspect exposure. Rotation takes effect immediately and doesn’t require contacting support.
• Identify tokens by their last four characters. The Integration tab shows the last four characters of each token, so you can tell which one to rotate without exposing the full value.

For the error responses returned when authentication fails, see the Errors guide.