Skip to content

Postman Collection Guide

The Contio Partner API includes a Postman collection with a pre-configured OAuth flow that lets you test the API without writing any code.

Getting the Collection

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

  1. Open Postman
  2. Click Import → Link
  3. Enter: https://docs.contio.ai/openapi/partner_postman_collection.json

Setting Up Variables

Before running the OAuth flow, configure these collection variables:

Variable Description Example
partner_client_id Your OAuth client ID abc123...
partner_client_secret Your OAuth client secret secret...
oauth_email Email of the user to authenticate user@example.com
redirect_uri Must match your registered redirect URI http://localhost:3000/callback
oauth_scopes Space-separated scopes to request openid profile meetings:read

To set variables:

  1. Click on the collection name
  2. Go to the Variables tab
  3. Fill in the values in the Current Value column
  4. Click Save

Running the OAuth Flow

The collection includes a 🔐 OAuth Flow (Run in Order) folder with 7 requests that walk you through the complete OAuth flow.

Step 1: Initiate Auth

Request: 1. Initiate Auth (sends OTP)

This sends a one-time password to the user's email.

  • What happens: An OTP is sent to {{oauth_email}}
  • Next step: Check the user's email inbox

Step 2: Verify OTP

Request: 2. Verify OTP (creates session)

Set the OTP first

Before running this request, set the otp_code collection variable to the 6-digit code from the email.

This verifies the OTP and creates an authenticated session.

  • What happens: Session cookie is stored automatically
  • Auto-captured: session_id variable

Request: 3. Grant Consent (get auth code)

This simulates the user granting permission for the requested scopes.

  • What happens: Authorization code is generated
  • Auto-captured: authorization_code variable

Step 4: Exchange Token

Request: 4. Exchange Token (get access token)

Exchanges the authorization code for tokens.

  • What happens: Tokens are returned
  • Auto-captured: oauth_token, refresh_token, id_token variables

OAuth flow complete!

After this step, you have valid tokens. The oauth_token variable is automatically used for all Partner User API requests.

Step 5: Test API Call

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

Makes a sample API call to verify the token works.

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

Step 6: Refresh Token (Optional)

Request: 6. Refresh Token (optional)

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

  • When to use: Access tokens expire after 24 hours
  • Auto-captured: New oauth_token and refresh_token

Step 7: Introspect ID Token (Optional)

Request: 7. Introspect ID Token (optional)

Examines the ID token to see its claims.

  • What it shows: User identity (sub, email), expiration, issuer
  • Try also: Change {{id_token}} to {{oauth_token}} to introspect the access token

Token Introspection

  • Access tokens return authorization info (scopes, client_id)
  • ID tokens return identity info (email, sub)
  • Refresh tokens return active: false (they're encrypted)

Troubleshooting

"Missing token parameter"

The oauth_token variable is empty. Run the OAuth flow first.

"Invalid OTP"

  • OTPs expire after 10 minutes
  • Make sure you're using the most recent OTP
  • Check for extra spaces when copying

"Session expired"

The authentication session timed out. Start over from Step 1.

"insufficient_scope"

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

  • The consent step was skipped
  • The requested scopes weren't granted

Re-run the OAuth flow and ensure Step 3 (Grant Consent) succeeds.

Tips

  • Run requests in order - Each step depends on the previous one
  • Check the Console - Postman logs helpful messages (View → Show Postman Console)
  • Variables are auto-saved - Tokens are captured automatically by test scripts
  • Use environments - Create separate environments for dev/staging/production

Next Steps