Postman Collection Guide¶

The Contio User API includes a Postman collection with a fully scripted OAuth 2.1 + PKCE flow that lets you test the API without writing any code — and without a browser round-trip. You log in with an email one-time code, and the collection handles PKCE, authorization, and token exchange for you.

Getting the Collection¶

Download the Postman collection from the OpenAPI page, or import it directly:

1. Open Postman
2. Click Import → Link
3. Enter: https://docs.contio.ai/user-api/openapi/user_postman_collection.json

Key Differences from Partner API¶

The User API uses OAuth 2.1 with PKCE instead of the Partner API's OAuth 2.0 flow:

Setting Up Variables¶

The collection comes pre-configured with sensible defaults. In most cases, you only need to set user_email to the account you want tokens for:

The following variables are captured automatically as you run the flow; you normally don't touch them: otp_session, session_jwt, oauth_token, refresh_token, code_verifier, code_challenge, oauth_state, authorization_code.

To modify variables:

1. Click on the collection name
2. Go to the Variables tab
3. Edit the Current Value column as needed
4. Click Save

About the client_id¶

The User API uses first-party OAuth — a flow designed for Contio's own applications (desktop app, CLI tools, etc.) to obtain tokens on behalf of a signed-in user.

Set client_id to the client ID issued for your first-party application. If you do not have a first-party client ID, use a Personal Access Token instead — set oauth_token to your PAT and skip the OAuth flow entirely.

If the OAuth flow doesn't work for your use case, use a Personal Access Token instead — set oauth_token to your PAT and skip the flow entirely.

Available Scopes¶

The workspace scopes (workspace:read, workspace:write) cannot be requested through this OAuth flow; the authorize step rejects them. To call the Workspace endpoints, set oauth_token to a workspace API key instead.

Running the OAuth 2.1 + PKCE Flow¶

The collection includes a 🔐 OAuth 2.1 + PKCE Flow (Run in Order) folder with requests that walk you through the complete OAuth flow. Run them top to bottom.

Step 1: Log In — Send OTP¶

Request: 1. Log In — Send OTP

Sends a 6-digit one-time code to user_email and starts a login session.

• Before you run it: Set the user_email variable to your Contio account email
• What happens: An OTP email is sent; the login session is captured into otp_session
• Auto-captured: otp_session
• If you get 404: That email has no Contio account — sign up in the web app first

Step 2: Log In — Verify OTP¶

Request: 2. Log In — Verify OTP

Verifies the code and completes login.

• Before you run it: Set otp_code to the 6-digit code from your email
• What happens: Returns your session JWT
• Auto-captured: session_jwt (used as the Bearer token for the authorize step)

Step 3: Generate PKCE Parameters¶

Request: 3. Generate PKCE Parameters

Fetches the OIDC discovery document and generates the required PKCE parameters.

• What happens:
• Fetches the OpenID Connect discovery document
• Generates a cryptographically secure code_verifier
• Computes the S256 code_challenge
• Generates a random state for CSRF protection
• Auto-captured: code_verifier, code_challenge, oauth_state

Step 4: Authorize¶

Request: 4. Authorize (auto-captures code)

Calls /v1/oauth/authorize with your session JWT. Because first-party OAuth auto-approves, there is no consent screen — the endpoint returns a 302 redirect and the collection reads the authorization code straight from the Location header.

• What happens:
• Automatic redirect following is disabled so the 302 can be inspected
• The code is captured into authorization_code
• The returned state is verified against oauth_state
• Auto-captured: authorization_code
• If you get 401: Your session_jwt is missing or expired — re-run steps 1-2

Step 5: Exchange Token¶

Request: 5. Exchange Token (get access token)

Exchanges the authorization code + PKCE verifier for tokens.

• What happens: Tokens are returned (no client secret needed!)
• Auto-captured: oauth_token, refresh_token

Step 6: Test API Call¶

Request: 6. Test API Call (verify token works)

Makes a sample API call to verify the token works.

• What it does: Fetches your recent meetings
• Expected result: 200 OK with meeting data (or empty array)

Step 7: Refresh Token (Optional)¶

Request: 7. Refresh Token (optional)

Use this to get a new access token when the current one expires.

• When to use: Access tokens expire after 1 hour
• Important: Refresh tokens rotate — each refresh returns a NEW refresh token and invalidates the old one
• Lifetime: Refresh tokens are valid for 30 days, and each rotation resets that window — refreshing at least once every 30 days keeps the session alive
• Auto-captured: New oauth_token and refresh_token

Step 8: Revoke Token (Optional)¶

Request: 8. Revoke Token (optional)

Revokes a token and its rotation chain.

• What it does: Invalidates the specified token
• Auth: Sends your session_jwt (this endpoint requires an authenticated user session)
• Note: Always returns 200 per RFC 7009, even for unknown tokens

Using Personal Access Tokens (PAT)¶

For automation or when you don't want to use the OAuth flow, you can use a Personal Access Token:

1. Generate a PAT from the Contio web app (Settings → API Tokens)
2. In Postman, set the oauth_token variable to your PAT value
3. Skip the OAuth flow and use any API endpoint directly

PATs are prefixed with cto_pat_v1_ and expire after a fixed period chosen at creation (30, 60, 90, 180, or 365 days), or when revoked.

See Personal Access Tokens for more details.

Troubleshooting¶

404 "Email not found" on Send OTP¶

The user_email has no Contio account. Sign up in the web app first, then re-run Step 1.

401 on Verify OTP¶

The code was wrong or expired. Re-run Step 1 to get a fresh code, then Verify with the new otp_code.

401 (no Location header) on Authorize¶

Your session_jwt is missing or expired. Re-run Steps 1-2 to log in again, then Step 3 and Step 4.

"Missing token parameter"¶

The oauth_token variable is empty. Run the OAuth flow first, or set a PAT.

"invalid_grant" on token exchange¶

• The authorization code may have expired (codes expire quickly)
• The PKCE verifier doesn't match the challenge
• The redirect_uri doesn't match what was used in the authorize request

Solution: Re-run Steps 3-5 (generate fresh PKCE, authorize, exchange).

"invalid_request" on authorize¶

• Check that redirect_uri is a loopback address (http://127.0.0.1:PORT or http://localhost:PORT)
• Ensure you ran Step 3 first so code_challenge and oauth_state are populated
• Verify response_type is code

"insufficient_scope"¶

The token doesn't have the required scopes. This usually means:

• The requested scopes in oauth_scopes don't include what the endpoint needs
• The user didn't approve all requested scopes

Solution: Re-run the OAuth flow with the correct scopes.

"401 Unauthorized" on API calls¶

• The access token may have expired (1 hour lifetime)
• Use the Refresh Token request to get a new access token
• Or re-run the full OAuth flow

Tips¶

• Run requests in order — Each step depends on the previous one
• Check the Console — Postman logs helpful messages (View → Show Postman Console)
• No browser needed — Login and authorization are fully scripted; you only paste the emailed OTP code
• Variables are auto-saved — Tokens and codes are captured automatically by test scripts
• Reuse your session — Steps 3-5 can be re-run without logging in again, as long as session_jwt is still valid
• Use environments — Create separate environments for dev/staging/production (update baseUrl)
• No client secret — PKCE replaces the need for a client secret

Optional Parameters and Request Bodies¶

Requests ship ready to send without leaving placeholder values in the request:

• Optional query parameters and headers are disabled. For example, q, limit and offset on List or search canvases, and Idempotency-Key on create requests. Tick the checkbox next to a parameter or header and set its value to send it. Required parameters (such as start_date/end_date on List calendar events) stay enabled.
• Example bodies include only required fields and enum examples. Optional fields such as template_id, due_date or is_instant are left out. Add any field you need from the API reference. Replace the remaining <string> placeholders before sending. A request whose fields are all optional, such as Update workspace settings, ships with an empty {} body. Add the fields you want to change, because the API rejects an update with no fields (400).

API Endpoints Overview¶

The collection includes all User API endpoints organized by category:

Next Steps¶

• Authentication Guide — Implement OAuth 2.1 + PKCE in your application
• Personal Access Tokens — Use PATs for automation
• API Reference — Full endpoint documentation