API tokens and OAuth apps

The Portal API supports two credential types that let you authenticate API requests. This guide explains what each type is, when to use it, and how they differ in security and rotation behavior.

Two credential types

API tokens and OAuth apps are two distinct authentication methods with different design goals. Choose which one to use based on your integration pattern:

Aspect	API Tokens	OAuth Apps
Use case	Server-to-server integrations, scripts, backend services	User-facing applications, multi-user access
Setup	Simple—create and use immediately	More complex—requires user authorization flow
Token lifetime	Long-lived (customizable, default 2 years)	Access tokens expire after 24 hours
Refresh mechanism	Rotate to get new token value	Use refresh token to get new access token
Rotation behavior	7-day grace period (both tokens work)	Immediate invalidation (no grace period)
Best for	Automation, CI/CD, webhooks	Web apps, mobile apps, user consent flows

API tokens

What they are

An API token is a simple, long-lived JSON Web Token (JWT) credential consisting of two parts:

• Token ID (X-Plntr-App-Id) — Your application identifier, stable across rotations
• Token Value (X-Plntr-App-Token) — The JWT you send with each request

API tokens are stored securely and never transmitted outside your authorization requests.

When to use them

Use API tokens for:

• Server-to-server integrations
• Automated scripts and workflows
• Backend services and microservices
• CI/CD pipelines
• Webhooks and event handlers
• Getting started and prototyping

Anatomy of a token

When you create an API token, you receive:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production API Token",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenHint": "...ssw5c",
  "expiresAt": "2028-02-21T12:00:00Z",
  "createdAt": "2026-02-21T12:00:00Z"
}

Field	Purpose
id	Token identifier—use as X-Plntr-App-Id
token	Token value (JWT)—use as X-Plntr-App-Token
tokenHint	Last 4 characters for identification
expiresAt	When token expires (defaults to 2 years)

Save your token immediately

The token value is only shown once when created. Store it securely. If you lose it, you must rotate the token to get a new value.

Token rotation and grace period

API token rotation enables zero-downtime credential updates. When you rotate a token:

1. Rotate — Call the rotate endpoint to get a new token value
2. Grace period begins — Both old and new tokens work for 7 days
3. Update your systems — Deploy the new token to your applications
4. Verify — Test that everything works with the new token
5. Revoke previous (optional) — Manually end the grace period early
6. Grace period ends — Old token automatically expires

This grace period prevents service interruption when updating credentials across multiple systems.

curl -X POST https://manage.youriguide.com/api/v1/tokens/550e8400-e29b-41d4-a716-446655440000/rotate \
  -H "X-Plntr-App-Id: $APP_ID" \
  -H "X-Plntr-App-Token: $APP_TOKEN"

After rotation, both the old and new tokens work until the grace period expires:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.NEW_TOKEN.xyz789",
  "previousToken": {
    "hint": "...ssw5c",
    "status": "active",
    "expiresAt": "2026-02-28T12:00:00Z"
  }
}

Zero-downtime updates

Deploy the new token to all systems during the 7-day grace period, then optionally revoke the old token once verified.

OAuth apps

What they are

An OAuth app implements the OAuth 2.0 standard authorization flow, allowing users to grant your application access to their data. OAuth apps consist of:

• Client ID — Your application identifier (analogous to username)
• Client Secret — Your application secret (analogous to password)
• Authorization endpoint — Where users log in and grant permission
• Token endpoint — Where you exchange authorization codes for tokens

Unlike API tokens, OAuth apps support user authorization flows and multi-user access patterns.

When to use them

Use OAuth apps for:

• Web applications with user login
• Mobile applications
• Third-party integrations requiring user consent
• Applications accessing data on behalf of multiple users
• Applications that need refresh tokens
• Any scenario where users should explicitly authorize your app

The authorization flow

OAuth implements a four-step authorization flow:

Step 1: Authorization request

Direct users to the authorization endpoint:

https://manage.youriguide.com/api/v1/oauth2/authorize?\
response_type=code&\
client_id=$CLIENT_ID&\
redirect_uri=https://yourapp.com/oauth/callback&\
state=random-state-string

The user logs in (if needed) and reviews the permissions your app requests.

Step 2: Authorization code

After granting permission, the user is redirected back to your application with an authorization code:

https://yourapp.com/oauth/callback?code=AUTH_CODE&state=random-state-string

Step 3: Exchange for tokens

Exchange the authorization code for access and refresh tokens:

curl -X POST https://manage.youriguide.com/api/v1/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "$CLIENT_ID",
    "client_secret": "$CLIENT_SECRET",
    "code": "$AUTHORIZATION_CODE",
    "redirect_uri": "https://yourapp.com/oauth/callback"
  }'

Step 4: Use the access token

Use the access token in API requests:

curl -X POST https://manage.youriguide.com/api/v1/integrations/test \
  -H "X-Plntr-App-Id: $CLIENT_ID" \
  -H "X-Plntr-App-Token: $ACCESS_TOKEN"

Custom headers, not Bearer tokens

Unlike standard OAuth, the Portal API does NOT use Authorization: Bearer. Always use X-Plntr-App-Id and X-Plntr-App-Token headers.

Token lifetimes

OAuth tokens have fixed expiration times:

Token	Lifetime	Refresh
Access token	24 hours	Use refresh token to get new one
Refresh token	1 year	Cannot be refreshed; must re-authorize
Authorization code	10 minutes	Single-use; expires after one exchange

When the access token expires, use the refresh token to get a new one without requiring user re-authorization:

curl -X POST https://manage.youriguide.com/api/v1/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "$CLIENT_ID",
    "client_secret": "$CLIENT_SECRET",
    "refresh_token": "$REFRESH_TOKEN"
  }'

Scopes

Scopes limit what your credentials can access. Every credential must have at least one scope, and different tokens can have different scopes. This implements the principle of least privilege—each credential gets only the permissions it needs.

All available scopes

Scope	Description	Use Cases
iguide.list	List user's iGUIDEs and access metadata (read-only)	Dashboard displays, search functionality, iGUIDE enumeration
iguide.ro	Read iGUIDE metadata (excludes billing information)	Public integrations, viewer apps, read-only reports
iguide.rw	Read and write iGUIDE data (includes iguide.ro, excludes billing/tasks)	Data synchronization, gallery management, metadata updates
iguide.tasks	Create and manage iGUIDE tasks and work orders	Order management systems, scheduling tools, automation
iguide.billing	Access iGUIDE billing information	Accounting integrations, invoicing systems, financial reports
iguide.gallery	Upload and remove gallery images	Photo management tools, image processing pipelines
iguide.events	Receive and access iGUIDE events, dispatch webhooks	Real-time integrations, notification systems, event handlers
iguide.draft.ro	Download iGUIDE draft data	Data processing pipelines, draft analysis tools
viewer.data	Access Viewer API data endpoints (includes RESO)	MLS integrations, property data syndication
banner.list	Access public banners	Contact information displays, banner lookups
credentials.manage	Manage API tokens and OAuth applications	Automated credential rotation, DevOps workflows, self-service platforms

Scope hierarchy

The iguide.rw scope automatically includes all permissions from iguide.ro. When selecting scopes, choose the most specific scopes that match your needs.

The credentials.manage scope

The credentials.manage scope is special—it grants permission to manage your own credentials (create, rotate, delete tokens and apps). This is required if you're building a self-service credential management system or automating credential rotation in CI/CD pipelines.

Bootstrapping credentials

You need at least one credential with credentials.manage scope to programmatically create additional credentials. Create your first credential manually in the Portal, then use it to bootstrap automated credential provisioning.

Scope validation for app-based authentication

When using app-based credentials (rather than session-based authentication) to create or update credentials via the API Management endpoints, the assigned scopes are validated against your app's own scopes. You cannot create tokens or apps with scopes that your requesting app doesn't have. This prevents privilege escalation.

For example, if your app has ["iguide.list", "iguide.ro"] scopes, you cannot create a new token with ["iguide.list", "iguide.rw"] because your app doesn't have the iguide.rw scope.

Session-based authentication (interactive Portal login) bypasses this validation.

Authentication headers

All API requests require two custom headers. No matter which credential type you use, the headers are the same:

curl -X POST https://manage.youriguide.com/api/v1/integrations/test \
  -H "X-Plntr-App-Id: $APP_ID" \
  -H "X-Plntr-App-Token: $APP_TOKEN"

Header	Source	Description
X-Plntr-App-Id	Token ID or Client ID	Your application identifier
X-Plntr-App-Token	Token Value or Access Token	The credential value

Pass both values exactly as provided—no modification needed.

Not standard OAuth Bearer tokens

The Portal API does not use the standard OAuth Authorization: Bearer header. Always use the two custom headers above.

Limits and constraints

Resource	Limit	Notes
API tokens per user	10	Both active and rotated (during grace period) count toward limit
OAuth apps per user	10	Soft-deleted apps don't count
API token grace period	7 days	After rotation, both tokens work for 7 days
API token expiration	Customizable	Default: 2 years
OAuth access token lifetime	24 hours	Fixed; cannot be customized
OAuth refresh token lifetime	1 year	Fixed; cannot be customized
OAuth secret rotation	Immediate	No grace period; old secret invalidated instantly

OAuth secret rotation differs from token rotation

API token rotation has a 7-day grace period. OAuth app secret rotation immediately invalidates the old secret. Update your application before rotating to avoid downtime.

Choosing the right method

Use an API token if:

• You're building a server-to-server integration
• Your application doesn't need user authorization
• You want the simplest setup (create, use immediately)
• You're building a backend service or CI/CD pipeline
• You need long-lived credentials (2 years default)
• You want a grace period when rotating credentials

Use an OAuth app if:

• You're building a user-facing application (web or mobile)
• Your application accesses data on behalf of multiple users
• You need user consent and authorization
• You want short-lived access tokens (24 hours)
• You need automatic token refresh via refresh tokens
• You're building a third-party integration

Quick decision tree

Does your app need user authorization?
├─ YES → Use OAuth App
│        (User login, multi-user, consent-required)
└─ NO → Use API Token
         (Server-to-server, automation, backend)

Next steps

• Authentication guide — Learn how to use credentials in API requests
• API Management guide — Create and manage credentials programmatically
• Manage API credentials tutorial — Step-by-step workflows
• Rate limiting guide — Understand usage limits

Related resources

• Authentication
• API Management
• Rate limiting
• Your first iGUIDE