IDP Management API

The IDP (Identity Provider) Management API enables identity provider administrators to manage identities and API keys for their hosted identities.

Info

This API is for identity provider administrators who host identities for other users (e.g., cloudillo.net service). For end-user identity operations, see IDP API.

Endpoints

List Managed Identities

GET /api/idp/identities

List all identities managed by this identity provider.

Query Parameters:

  • q (optional) - Search query
  • status (optional) - Filter by status
  • cursor (optional) - Pagination cursor
  • limit (optional) - Maximum results

Response:

{
  "data": [
    {
      "idTag": "alice.cloudillo.net",
      "email": "alice@example.com",
      "status": "active",
      "createdAt": "2025-01-01T00:00:00Z",
      "ownerIdTag": null,
      "dyndns": true
    },
    {
      "idTag": "bob.cloudillo.net",
      "email": "bob@example.com",
      "status": "active",
      "createdAt": "2025-01-02T00:00:00Z",
      "ownerIdTag": "alice.cloudillo.net",
      "dyndns": false
    }
  ],
  "time": 1705315800,
  "req_id": "req_xyz"
}

Example:

curl -H "Authorization: Bearer $IDP_TOKEN" \
  "https://cl-o.cloudillo.net/api/idp/identities?limit=50"

Create Identity

POST /api/idp/identities

Create a new identity under this provider.

Request Body:

{
  "idTag": "newuser.cloudillo.net",
  "email": "newuser@example.com",
  "ownerIdTag": "alice.cloudillo.net",
  "createApiKey": true,
  "apiKeyName": "Initial Key"
}

Response:

{
  "data": {
    "idTag": "newuser.cloudillo.net",
    "email": "newuser@example.com",
    "status": "pending",
    "createdAt": "2025-01-15T10:30:00Z",
    "apiKey": "clak_abc123xyz..."
  },
  "time": 1705315800,
  "req_id": "req_xyz"
}
Warning

The apiKey is only returned once when createApiKey: true. Store it securely.

Example:

curl -X POST -H "Authorization: Bearer $IDP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"idTag":"newuser.cloudillo.net","email":"newuser@example.com","createApiKey":true}' \
  "https://cl-o.cloudillo.net/api/idp/identities"

Get Identity Details

GET /api/idp/identities/{idTag}

Get details for a specific managed identity.

Path Parameters:

  • idTag - Identity tag (URL-encoded)

Response:

{
  "data": {
    "idTag": "alice.cloudillo.net",
    "email": "alice@example.com",
    "status": "active",
    "createdAt": "2025-01-01T00:00:00Z",
    "lastLoginAt": "2025-01-15T10:30:00Z",
    "ownerIdTag": null,
    "dyndns": true
  },
  "time": 1705315800,
  "req_id": "req_xyz"
}

Update Identity

PATCH /api/idp/identities/{idTag}

Update identity settings.

Path Parameters:

  • idTag - Identity tag (URL-encoded)

Request Body:

{
  "dyndns": true
}

Response:

{
  "data": {
    "idTag": "alice.cloudillo.net",
    "dyndns": true
  },
  "time": 1705315800,
  "req_id": "req_xyz"
}

Update Identity Address

PUT /api/idp/identities/{idTag}/address

Update the DNS address mapping for a managed identity. This is used for dynamic DNS updates when self-hosting.

Path Parameters:

  • idTag - Identity tag (URL-encoded)

Request Body:

{
  "address": "192.168.1.100"
}

Response:

{
  "data": {
    "idTag": "alice.cloudillo.net",
    "address": "192.168.1.100"
  },
  "time": 1705315800,
  "req_id": "req_xyz"
}

Delete Identity

DELETE /api/idp/identities/{idTag}

Delete a managed identity.

Path Parameters:

  • idTag - Identity tag (URL-encoded)

Response:

{
  "data": null,
  "time": 1705315800,
  "req_id": "req_xyz"
}

List API Keys for Identity

GET /api/idp/api-keys?idTag={idTag}

List API keys for a specific managed identity.

Query Parameters:

  • idTag - Identity tag to list keys for

Response:

{
  "data": [
    {
      "keyId": 1,
      "name": "Production Key",
      "createdAt": "2025-01-01T00:00:00Z",
      "lastUsedAt": "2025-01-15T10:30:00Z"
    }
  ],
  "time": 1705315800,
  "req_id": "req_xyz"
}

Create API Key for Identity

POST /api/idp/api-keys

Create a new API key for a managed identity.

Request Body:

{
  "idTag": "alice.cloudillo.net",
  "name": "New API Key"
}

Response:

{
  "data": {
    "keyId": 2,
    "name": "New API Key",
    "apiKey": "clak_newkey123...",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "time": 1705315800,
  "req_id": "req_xyz"
}

Revoke API Key

DELETE /api/idp/api-keys/{keyId}?idTag={idTag}

Revoke an API key for a managed identity.

Path Parameters:

  • keyId - Key ID to revoke

Query Parameters:

  • idTag - Identity tag the key belongs to

Response:

{
  "data": null,
  "time": 1705315800,
  "req_id": "req_xyz"
}

Client SDK Usage

import { createApiClient } from '@cloudillo/core'

const api = createApiClient({ idTag: 'cloudillo.net', authToken: idpToken })

// List managed identities
const identities = await api.idpManagement.listIdentities({ limit: 100 })

// Create new identity with API key
const newIdentity = await api.idpManagement.createIdentity({
  idTag: 'newuser.cloudillo.net',
  email: 'newuser@example.com',
  createApiKey: true,
  apiKeyName: 'Initial Key'
})
console.log('API Key:', newIdentity.apiKey) // Store securely!

// Get identity details
const identity = await api.idpManagement.getIdentity('alice.cloudillo.net')

// Update identity settings
await api.idpManagement.updateIdentity('alice.cloudillo.net', { dyndns: true })

// Delete identity
await api.idpManagement.deleteIdentity('olduser.cloudillo.net')

// Manage API keys
const keys = await api.idpManagement.listApiKeys('alice.cloudillo.net')
const newKey = await api.idpManagement.createApiKey({
  idTag: 'alice.cloudillo.net',
  name: 'Backup Key'
})
await api.idpManagement.deleteApiKey(keyId, 'alice.cloudillo.net')

Use Cases

Provisioning New Users

async function provisionUser(email: string, subdomain: string) {
  const idTag = `${subdomain}.cloudillo.net`

  // Create identity with initial API key
  const result = await api.idpManagement.createIdentity({
    idTag,
    email,
    createApiKey: true,
    apiKeyName: 'Setup Key'
  })

  // Send setup instructions with API key
  await sendSetupEmail(email, {
    idTag,
    apiKey: result.apiKey
  })

  return result
}

Automating Identity Management

// Deactivate inactive users
const identities = await api.idpManagement.listIdentities()

for (const identity of identities.data) {
  const daysSinceLogin = daysSince(identity.lastLoginAt)
  if (daysSinceLogin > 365) {
    await api.idpManagement.deleteIdentity(identity.idTag)
  }
}

See Also