Developer Portal

Welcome to the IDriftr Developer Portal. Our APIs allow you to integrate continuous KYB, trust propagation, and identity drift detection directly into your workflows.

IDriftr is built on a Deterministic Trust Engine. Every status check and verification request provides a detailed rationale, ensuring transparency in compliance decisions.

Authentication

All production API requests must be authenticated using a Bearer token. Include the token in the Authorization header on every request.

Authorization: Bearer <YOUR_API_TOKEN>

Making Authenticated Requests

Send the token as a Bearer credential in the header.

# curl
curl -s \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  https://idriftr.com/api/companies/<company_id>/trust-status/

# Python (requests)
import requests
headers = {"Authorization": "Bearer <YOUR_API_TOKEN>"}
r = requests.get("https://idriftr.com/api/companies/<company_id>/trust-status/", headers=headers)
print(r.status_code, r.json())

Token Rotation & Security

Tokens can be revoked server-side at any time. Keep a short rotation cadence (e.g., 90 days).
Scope tokens per environment (staging vs production) and per integration.
If a token is compromised, revoke it immediately and create a replacement.

Error Responses

If the header is missing or invalid, the API responds with 401 Unauthorized:

{
  "error": "authentication_required",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer <token>"
}

Obtain a Bearer Token (Production)

To call production APIs, first exchange your client_id and client_secret (issued for your Organization) and your user credentials for a short-lived Bearer token.

POST /api/auth/token/

Field	Type	Required	Description
`client_id`	string	Yes	Issued to your Organization. Contact support if you don't have one.
`client_secret`	string	Yes	Paired secret for the client.
`username`	string	Yes	Portal username of a user in the Organization.
`password`	string	Yes	Password for the user.
`expires_in_minutes`	integer	No	How long the token should be valid (1–240). Defaults to 60.

Example request:

# curl
curl -s -X POST https://idriftr.com/api/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "cli_...",
    "client_secret": "sec_...",
    "username": "api-user@example.com",
    "password": "********",
    "expires_in_minutes": 90
  }'

# Python (requests)
import requests
payload = {
  "client_id": "cli_...",
  "client_secret": "sec_...",
  "username": "api-user@example.com",
  "password": "********",
  "expires_in_minutes": 90,
}
r = requests.post("https://idriftr.com/api/auth/token/", json=payload)
r.raise_for_status()
access_token = r.json()["access_token"]
headers = {"Authorization": f"Bearer {access_token}"}
# Use it:
requests.get("https://idriftr.com/api/commercial/contracts/", headers=headers)

Successful response:

{
  "access_token": "<64-hex-secret>",
  "token_type": "Bearer",
  "expires_in": 5400,
  "expires_at": "2026-01-20T12:34:56Z",
  "organization": {"id": "...", "name": "Acme Corp"},
  "user": {"id": 123, "username": "api-user"}
}

Errors:

{
  "error": "invalid_client" | "invalid_grant" | "access_denied",
  "message": "..."
}

Identity API

Manage and query the trust status of legal entities and their internal relationships.

GET /api/companies/{company_id}/trust-status/

Returns the current verified status and the latest trust assessment rationale for a company.

Parameter	Type	Description
`company_id`	UUID	The unique identifier of the company.

GET /api/companies/{company_id}/authority-matrix/

Provides a structured list of all persons authorized to act on behalf of the company.

GET /api/companies/{company_id}/identity-drift/

Lists unprocessed changes detected in the registry that may impact the entity's trust level.

GET /api/companies/{company_id}/open-actions/

Returns a list of required actions (e.g., verifying a new director) to maintain or restore trust status.

GET /api/companies/{company_id}/audit-timeline/

Provides a complete historical record of all trust-impacting events for this entity.

Issuance API

Handle the lifecycle of portable identity assertions and Relying Party configurations.

POST /api/issuance/assertions/verify/

Validates a portable assertion ID for a specific Relying Party.

{
  "assertion_id": "uuid",
  "relying_party_id": "uuid"
}

GET /api/issuance/relying-parties/{rp_id}/

Retrieves metadata and allowed scopes for a registered Relying Party.

Commercial API

Monitor service level agreements, usage, and trust contracts.

GET /api/commercial/contracts/

Lists all active trust contracts and their required confidence thresholds.

Query Param	Type	Description
`rp_id`	UUID	Filter by Relying Party ID.

GET /api/commercial/usage/

Provides a detailed breakdown of API usage for a specific Relying Party.

Query Param	Type	Description
`rp_id` Required	UUID	The Relying Party ID to report on.

GET /api/commercial/trust/slas/

Returns the real-time SLA status of a company against its trust contracts.

Sandbox & Simulation

Use these endpoints in our sandbox environment to simulate identity drift and test your propagation logic.

GET /api/demo/state/

Returns the current state of the demo environment, including available test companies and assertions.

POST /api/demo/simulate-drift/

Triggers a simulated registry change for a test company to observe the trust propagation effects.