Applications & API Keys

An application is the container for your integration with PIP. Each application has an OAuth client and can issue M2M API keys.

Application model

{
  "id": "app_xxxx",
  "slug": "my-backend",
  "name": "My Backend Service",
  "status": "active",
  "ownerOrgId": "org_xxxx",
  "oauthClientId": "client_xxxx",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Register an application

POST /applications
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "name": "My Backend Service",
  "slug": "my-backend",
  "description": "Internal data pipeline"
}

Link an OAuth client

Each application links to exactly one Hydra OAuth client.

POST /applications/:slug/oauth-client
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "grantTypes": ["client_credentials"],
  "redirectUris": []
}

Returns clientId and clientSecret. Store the secret securely — it won't be shown again.

API Keys (M2M)

API keys are long-lived bearer tokens bound to an application. Use them for server-to-server calls.

⚠️

API keys are application credentials — they belong to the application, not a user. Anyone with the key has the application's access level.

Create an API key

POST /applications/:id/api-keys
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "name": "production-pipeline",
  "scopes": ["pip:read"],
  "expiresAt": "2027-01-01T00:00:00.000Z"
}

Response (key shown once):

{
  "id": "key_xxxx",
  "name": "production-pipeline",
  "token": "pip_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scopes": ["pip:read"],
  "expiresAt": "2027-01-01T00:00:00.000Z",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

List API keys

GET /applications/:id/api-keys
Authorization: Bearer <token>

Returns metadata only — no tokens.

Revoke an API key

DELETE /applications/:id/api-keys/:keyId
Authorization: Bearer <token>

Takes effect immediately.

Using an API key

GET /identity/users
Authorization: Bearer pip_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Access Control Overview