Authentication

Every request carries an API key of your organization. The key decides which organization’s data you read, and which operations you may call.

The header

Send the key in the Authorization header, exactly like this:

Authorization: Bearer mcf_your_key

Bearer with a capital B, one space, then the key: nothing before, nothing after. The API accepts a key in no other place. A key in a query string or in another header is refused.

Keys are for servers. Never ship one in a web page or a mobile app: the API answers no browser (CORS) request, and anyone who reads the key can use it.

Creating keys

An administrator of your organization creates keys in the console, under Integrations (« Intégrations »). The organization owns its keys: every administrator sees and can revoke all of them.

• The key is shown once, in the answer to its creation. Store it in your secret manager; it cannot be displayed again.
• Every key has an expiry date, at most 366 days after its creation.
• An organization holds at most 20 keys that are not revoked, expired ones included.

Use one key per application. You can then revoke one without touching the others.

Scopes

A key carries one or more scopes, chosen at its creation. Each operation needs one of them:

Expanding a linked event (expand[]=event) also needs events_read. A key that lacks the scope of an operation gets 403 api_key_scope_missing, and the message names the missing scope.

To see the scopes and the expiry of the key you are using, call GET/v1/account:

{
  "id": "ORG-7b2c9e40-1a5d-4c83-9f6e-3d8a0b4c2e71",
  "object": "account",
  "api_key": {
    "id": "APIK-4f8a2c1e-9b3d-4e6a-8c7f-2a1e5d9b0c34",
    "scopes": [
      "calls_for_papers_read",
      "events_read",
      "registrations_read"
    ],
    "expires_at": 1824076800
  }
}

expires_at is a Unix timestamp, in seconds.

Expiry and revocation

An administrator revokes a key in the console. Revocation is final: create a new key rather than trying to restore an old one.

A revoked or expired key stops working within 60 seconds. During that minute, calls with it can still succeed.

To rotate a key without downtime:

1. Create the new key.
2. Deploy it in your application.
3. Revoke the old one.

Authentication errors

• 401 api_key_invalid: the header is missing or malformed, or the key is unknown, revoked or expired. Every one of these cases gets the same answer, on purpose: the API never tells which.
• 402 plan_feature_missing: your organization’s plan does not include the API. Calls for papers and papers also need the plan’s calls for papers module.
• 423 organization_suspended: your organization is suspended. Every call answers this until it is reactivated.

Only one document needs no key: the contract itself, GET /v1/openapi.json.