Common Paper supports agentic signup, which lets an AI agent or integration create a Common Paper account from code, without anyone logging into the web app first. If someone asks an agent to create a Common Paper account, the agent can follow the steps below to sign up and receive an API key for all subsequent calls.
When to use agentic signup
Use agentic signup when you need to create a brand new Common Paper account programmatically. This is the right path when an agent is onboarding a new organization and there is no existing account to authenticate against.
If you already have an account and an API key, you do not need agentic signup. Authenticate with your existing key instead. See Authentication for more.
How it works
Agentic signup relies on a provision key, a one-time credential that an agent exchanges for a real account. The flow is a two-step exchange:
Mint a provision key with
POST /v1/keys. This endpoint is public and unauthenticated. It returns a one-time provision key.Redeem the provision key with
POST /v1/accounts. Pass the provision key in the Authorization header. This creates the organization and its first user, and returns a production API key.
A provision key can only be redeemed once. After redemption, use the returned production API key for everything else.
Step 1: Mint a provision key
Call POST /v1/keys with a contact_email. The integrator_name field is optional and is stored as metadata for attribution.
curl -X POST "https://api.commonpaper.com/v1/keys" \ -H "Content-Type: application/json" \ -d '{ "contact_email": "[email protected]", "integrator_name": "XYZ Co" }'A successful response returns 201 Created with the provision key in plaintext:
{ "key": "PROVISION_KEY_PLAINTEXT", "key_last_four": "wxyz", "contact_email": "[email protected]", "integrator_name": "XYZ Co" }This endpoint is rate-limited. A 422 response means the contact_email was missing, invalid, or used a throwaway domain.
Step 2: Redeem the provision key for an account
Send the provision key from Step 1 in the Authorization header. Provide the initial user's email and name, and the new organization's org_name. The user becomes the admin of the new organization.
curl -X POST "https://api.commonpaper.com/v1/accounts" \ -H "Authorization: Bearer PROVISION_KEY_PLAINTEXT" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected]", "name": "New User", "org_name": "Acme Co" }'
A successful response returns 201 Created with a production API key:
{ "api_key": "API_KEY_PLAINTEXT", "user_id": "USER_UUID", "organization_id": "ORG_UUID" }Store the api_key securely. Use it as the bearer token for all subsequent API calls.
Common errors when redeeming
Status | Meaning |
401 | Missing or invalid provision key. |
409 | The email is already in use. |
410 | The provision key has already been redeemed. Mint a new one. |
422 | A required field was missing or invalid. |
After signing up
Once you have a production API key, you are done with provision keys. Authenticate every other request with the production key:
curl -X GET "https://api.commonpaper.com/v1/agreements" \ -H "Authorization: Bearer API_KEY_PLAINTEXT"
NOTE: The provision key cannot be redeemed again to recover the API key, so store the API key securely as soon as you receive it.
Learn more
Using Provision Keys - the full agentic signup reference
Authentication - using your API key on subsequent calls
Common Paper API documentation - everything else the API can do