Skip to main content

Authentication

Authenticate your Portal API requests using API tokens or OAuth apps—both available via self-service in the iGUIDE Portal.

Required headers​

All API requests need two custom headers:

HeaderDescription
X-Plntr-App-IdYour application ID (token ID or client ID)
X-Plntr-App-TokenYour access token (token value or OAuth access token)

Pass both values exactly as provided—no modification needed.

Example request:

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"
Not standard Bearer tokens

Unlike standard OAuth, the Portal API does NOT use Authorization: Bearer. Always use the two custom headers above.

Authentication methods​

Choose between two authentication methods based on your use case:

API tokens are simple, long-lived credentials perfect for server-to-server integrations, scripts and backend services.

Quick start:

  1. Navigate to Portal Settings → API Management → API Tokens
  2. Create a new token with the scopes you need
  3. Save the Token ID (X-Plntr-App-Id) and Token Value (X-Plntr-App-Token) immediately
warning

Token values are only shown once. Save them securely.

Learn more: See API tokens and OAuth apps for detailed information about token rotation, grace periods and best practices.

OAuth apps (for user authorization flows)​

OAuth apps implement OAuth 2.0 authorization flows for user-facing applications, mobile apps and third-party integrations.

Quick start:

  1. Navigate to Portal Settings → API Management → OAuth Apps
  2. Create an OAuth app with your redirect URIs and required scopes
  3. Save the Client ID and Client Secret immediately
  4. Implement the OAuth 2.0 flow in your application

Learn more: See API tokens and OAuth apps for the complete OAuth 2.0 flow, token refresh mechanism and error handling.

Step-by-step guide: Follow Manage API credentials tutorial for detailed examples of creating, rotating and managing credentials.

Scopes​

Scopes limit what your credentials can access. Request only the minimum scopes your application needs:

ScopeDescription
iguide.listList user's iGUIDEs and access metadata (read-only)
iguide.roRead iGUIDE metadata (excludes billing)
iguide.rwRead and write iGUIDE data (includes iguide.ro, excludes billing/tasks)
iguide.tasksCreate and manage iGUIDE tasks and work orders
iguide.billingAccess iGUIDE billing information
iguide.galleryUpload and remove gallery images
iguide.eventsReceive iGUIDE events and dispatch webhooks
iguide.draft.roDownload iGUIDE draft data
viewer.dataAccess Viewer API data endpoints
banner.listAccess public banners
credentials.manageManage API tokens and OAuth applications

Learn more: See API tokens and OAuth apps for detailed scope descriptions and use cases.

Authentication errors​

401 Unauthorized​

Failed authentication returns HTTP 401:

{ "code": "unauthenticated" }

Common causes:

  • Invalid or expired token
  • Missing authentication headers
  • Token deleted or revoked
  • Incorrect header names (must be exact: X-Plntr-App-Id and X-Plntr-App-Token)

403 Forbidden​

Insufficient permissions returns HTTP 403:

{ "code": "permission_denied" }

Common causes:

  • Token lacks required scopes for the endpoint
  • Attempting to access resources owned by another user
  • Admin-only endpoint accessed with non-admin credentials

Testing your credentials​

Test your credentials using the test endpoint:

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"

Expected response:

{
  "appId": "your-app-id-here"
}

Next steps​