Authentication

Every request to /api/v2 is authenticated. You pass an API token as a bearer token in the Authorization header, and Archive checks it on every request. There are no unauthenticated operations.

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

The WORKSPACE-ID header shown here is required only for workspace-scoped operations — see the Workspaces guide. The Authorization header is required everywhere. 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))

Obtaining a token

Provision tokens yourself from the Integration tab in the Archive app. You do not need to contact support to get started.

• If your workspace belongs to an organization, the token is agency-wide: it can reach every workspace in the org, selected per request by the WORKSPACE-ID header.
• Otherwise, the token is scoped to the single workspace it was issued for.

The full token is shown once, at the moment you provision it. Archive stores only a hash and the last four characters, so afterward you can identify a token by its last four but never retrieve the full value again. Copy it into your secret store immediately.

Rotating and disabling tokens

Re-provisioning from the Integration tab rotates the token: the new token takes effect at once and the old one stops working on its very next request, so rotation is safe to use the moment you suspect a leak. A rotated token fails with HTTP 401 and the body {"errors":"Missing or invalid authentication token"} — the same response an entirely unknown token gets, because Archive keeps only the hash of the current token.

Pausing is separate from rotating. A token paused from the Integration tab keeps its identity but is refused with HTTP 401 and the body {"errors":"Account is disabled"}. If you rotate a credential that is currently paused, the replacement token is issued paused too — re-enable it before use.

Token hygiene

• Keep tokens server-side. Never ship a token to a browser, mobile app, or any other client you do not control.
• Store them in environment variables or a secret manager, not in source control.
• Rotate on suspicion. Rotation is immediate and self-serve; use it liberally.
• Identify by the last four. 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 shapes returned when authentication fails, see the Errors guide.