Identity Provider API

Overview

The Identity Provider (IDP) API enables identity management for Cloudillo’s DNS-based identity system. It allows identity providers to register, manage, and activate identities within their domain.

IDP Availability

IDP functionality must be enabled for the tenant. When disabled, all IDP endpoints return 404 Not Found.

Public Endpoints

These endpoints are available without authentication.

Get IDP Info

GET /api/idp/info

Get public information about this Identity Provider. Used by registration UIs to help users choose a provider.

Authentication: None

Response:

{
  "data": {
    "domain": "cloudillo.net",
    "name": "Cloudillo",
    "info": "Free identity hosting for the Cloudillo network",
    "url": "https://cloudillo.net/identity"
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}
Field Type Description
domain string Provider domain (e.g., cloudillo.net)
name string Display name of the provider
info string Short description (pricing, terms)
url string Optional URL for more information

Check Availability

GET /api/idp/check-availability

Check if an identity tag is available for registration.

Authentication: Required

Query Parameters:

Parameter Type Required Description
idTag string Yes Identity to check (e.g., alice.cloudillo.net)

Response:

{
  "data": {
    "available": true,
    "idTag": "alice.cloudillo.net"
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Example:

const result = await api.idp.checkAvailability({
  idTag: 'alice.cloudillo.net'
})
if (result.data.available) {
  // Identity is available for registration
}
Domain Restriction

The identity domain must match the authenticated registrar’s domain. You cannot check availability for identities in other domains.

Activate Identity

POST /api/idp/activate

Activate an identity using a reference token. This is used when the identity owner activates their identity after the registrar has created it.

Authentication: None (uses reference token)

Request:

{
  "refId": "ref_abc123def456"
}
Field Type Required Description
refId string Yes The activation reference ID

Response:

{
  "data": {
    "idTag": "alice.cloudillo.net",
    "status": "active",
    "address": "cloudillo.example.com"
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Identity Management

List Identities

GET /api/idp/identities

List identities managed by the authenticated user.

Authentication: Required

Query Parameters:

Parameter Type Required Description
email string No Filter by email (partial match)
registrarIdTag string No Filter by registrar
ownerIdTag string No Filter by owner
status string No Filter by status: pending, active, suspended
limit number No Maximum results to return
offset number No Pagination offset

Response:

{
  "data": [
    {
      "idTag": "alice.cloudillo.net",
      "email": "alice@example.com",
      "registrarIdTag": "admin.cloudillo.net",
      "ownerIdTag": null,
      "address": "cloudillo.example.com",
      "addressUpdatedAt": 1735000000,
      "status": "active",
      "createdAt": 1734900000,
      "updatedAt": 1735000000,
      "expiresAt": 1766436000
    }
  ],
  "time": 1735000000,
  "reqId": "req_abc123"
}

Example:

const identities = await api.idp.identities.list({
  status: 'active',
  limit: 20
})

Create Identity

POST /api/idp/identities

Create a new identity. The authenticated user becomes the registrar.

Authentication: Required

Request:

{
  "idTag": "alice.cloudillo.net",
  "email": "alice@example.com",
  "ownerIdTag": null,
  "address": "cloudillo.example.com"
}
Field Type Required Description
idTag string Yes Identity tag (must be in registrar’s domain)
email string No Email address (required if no ownerIdTag)
ownerIdTag string No Owner identity for community-owned identities
address string No Initial server address

Response:

{
  "data": {
    "idTag": "alice.cloudillo.net",
    "email": "alice@example.com",
    "registrarIdTag": "admin.cloudillo.net",
    "status": "pending",
    "createdAt": 1735000000,
    "updatedAt": 1735000000,
    "expiresAt": 1766436000,
    "apiKey": "clid_abc123..."
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}
API Key

The apiKey field is only returned during creation. Store it securely - it cannot be retrieved later.

Example:

const identity = await api.idp.identities.create({
  idTag: 'alice.cloudillo.net',
  email: 'alice@example.com'
})
console.log('Created identity:', identity.data.idTag)
console.log('API key:', identity.data.apiKey) // Store this!

Get Identity

GET /api/idp/identities/{id}

Get details of a specific identity.

Authentication: Required (must be owner or registrar)

Path Parameters:

Parameter Type Description
id string Identity tag (e.g., alice.cloudillo.net)

Response:

{
  "data": {
    "idTag": "alice.cloudillo.net",
    "email": "alice@example.com",
    "registrarIdTag": "admin.cloudillo.net",
    "ownerIdTag": null,
    "address": "cloudillo.example.com",
    "addressUpdatedAt": 1735000000,
    "status": "active",
    "createdAt": 1734900000,
    "updatedAt": 1735000000,
    "expiresAt": 1766436000
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Update Identity Address

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

Update the server address for an identity.

Authentication: Required (must be owner or registrar while pending)

Path Parameters:

Parameter Type Description
id string Identity tag

Request:

{
  "address": "new-server.example.com",
  "autoAddress": false
}
Field Type Required Description
address string No New server address
autoAddress boolean No If true and no address provided, use requester’s IP

Response:

{
  "data": {
    "idTag": "alice.cloudillo.net",
    "address": "new-server.example.com",
    "addressUpdatedAt": 1735000000,
    "status": "active"
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Delete Identity

DELETE /api/idp/identities/{id}

Delete an identity. This action cannot be undone.

Authentication: Required (must be owner or registrar while pending)

Path Parameters:

Parameter Type Description
id string Identity tag to delete

Response:

{
  "data": {
    "deleted": true,
    "idTag": "alice.cloudillo.net"
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}
Permanent Deletion

Deleting an identity is permanent. The identity tag may be reused after deletion.

API Key Management

API keys provide programmatic access to identity operations.

Create API Key

POST /api/idp/api-keys

Create a new API key for the authenticated identity.

Authentication: Required

Request:

{
  "name": "Server automation",
  "expiresAt": 1766436000
}
Field Type Required Description
name string No Human-readable name
expiresAt number No Expiration timestamp (Unix seconds)

Response:

{
  "data": {
    "apiKey": {
      "id": 123,
      "idTag": "alice.cloudillo.net",
      "keyPrefix": "clid_abc",
      "name": "Server automation",
      "createdAt": 1735000000,
      "lastUsedAt": null,
      "expiresAt": 1766436000
    },
    "plaintextKey": "clid_abc123def456ghi789..."
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}
Store Key Securely

The plaintextKey is only shown once during creation. Store it securely - it cannot be retrieved later.

List API Keys

GET /api/idp/api-keys

List API keys for the authenticated identity.

Authentication: Required

Query Parameters:

Parameter Type Required Description
limit number No Maximum results
offset number No Pagination offset

Response:

{
  "data": [
    {
      "id": 123,
      "idTag": "alice.cloudillo.net",
      "keyPrefix": "clid_abc",
      "name": "Server automation",
      "createdAt": 1735000000,
      "lastUsedAt": 1735050000,
      "expiresAt": 1766436000
    }
  ],
  "time": 1735000000,
  "reqId": "req_abc123"
}

Get API Key

GET /api/idp/api-keys/{id}

Get details of a specific API key.

Authentication: Required

Path Parameters:

Parameter Type Description
id number API key ID

Response:

{
  "data": {
    "id": 123,
    "idTag": "alice.cloudillo.net",
    "keyPrefix": "clid_abc",
    "name": "Server automation",
    "createdAt": 1735000000,
    "lastUsedAt": 1735050000,
    "expiresAt": 1766436000
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Delete API Key

DELETE /api/idp/api-keys/{id}

Delete an API key. The key will immediately become invalid.

Authentication: Required

Path Parameters:

Parameter Type Description
id number API key ID to delete

Response:

{
  "data": {
    "deleted": true,
    "id": 123
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Authorization Model

IDP operations use a two-tier authorization model:

Role Access Duration
Owner Full control Permanent
Registrar Create, view, update, delete Only while status is pending

After an identity is activated (status changes from pending to active), the registrar loses control. Only the owner retains access.

Identity Status

Status Description
pending Created but not yet activated by owner
active Activated and operational
suspended Temporarily disabled by administrator

See Also