# Aho API

Verifiable Credentials API for issuance, verification, and management.

## Documentation

New to verifiable credentials? These resources will help:

- [Glossary](/docs/glossary) — Key terms: DID, VC, VP, holder, issuer, verifier, and more
- [Credential Formats](/docs/formats) — Comparison of JWT-VC, SD-JWT-VC, and mdoc formats
- [Developer Guides](/developers) — Step-by-step integration tutorials
- [Verifiable Credentials API Guide](/developers/verifiable-credentials-with-aho) — Issue and verify credentials
- [Revocation API Guide](/developers/revocation-api) — Revoke and suspend credentials

## Base URL

All API requests are made to the `api` subdomain:

```
https://api.aho.com
```

For example, `/v1/issuer/credentials` becomes `https://api.aho.com/v1/issuer/credentials`.

## Authentication

Different API paths require different authentication methods:

| Path Prefix | Authentication | Description |
|-------------|----------------|-------------|
| `/v1/issuer/*` | Issuer API Key (`X-API-Key` header) | Credential issuance, schemas, data sources, automations |
| `/v1/verifier/*` | Verifier API Key (`X-API-Key` header) | Presentation requests, verification |
| `/v1/account/*` | Account API Key (`X-API-Key` header) | Domains, signing keys, webhooks, API key management |
| `/v1/holder/*` | Bearer Token (`Authorization` header) | Holder wallet operations |
| `/v1/hooks/*` | Token in URL path | External webhook triggers (no API key needed) |
| `/v1/health` | None (public) | Health check endpoint |
| `/v1/schemas` | None (public) | Public schema registry |

**API Keys:** Obtain from your dashboard under Settings > API Key. Include as `X-API-Key` header.

**Webhook Tokens:** Generated per-automation via `POST /v1/issuer/automations/{id}/webhook`.
The token is embedded in the trigger URL for simple external system integration.

## Rate Limits

All API endpoints are rate limited to prevent abuse. Limits are applied per API key.

| Category | Limit | Applies To |
|----------|-------|------------|
| General | 60 requests/minute | All API endpoints |
| Batch Operations | 30 requests/minute | Bulk credential issuance, batch revocation |
| Sensitive Operations | 5 requests/minute | Domain creation, signing key creation, API key operations |
| Automation Triggers | 10 requests/minute | Automation trigger endpoints |
| Data Source Tests | 5 requests/minute | Data source connection tests |

When rate limited, the API returns HTTP 429 with a `Retry-After` header indicating seconds to wait.

## API Endpoints

### [Credential Schemas](https://aho.com/docs/api/credential-schemas.md)

define the structure and validation rules for your verifiable credentials.

A schema specifies:
- The credential type (e.g., "EmployeeBadgeCredential")
- The claims/fields the credential contains (name, title, department, etc.)
- Validation rules for each field (required, format, allowed values)
- Supported credential formats (JWT-VC, SD-JWT-VC, mdoc)

**Workflow:** Create a schema first, then use it when issuing credentials or setting up automations.
New schemas start in "draft" status and must be activated before use.

- `GET /v1/issuer/schemas` — [List issuer credential schemas](https://aho.com/docs/api/credential-schemas/list.md)
- `GET /v1/issuer/schemas/{id}` — [Get credential schema details](https://aho.com/docs/api/credential-schemas/get.md)
- `POST /v1/issuer/schemas` — [Create a credential schema](https://aho.com/docs/api/credential-schemas/create.md)
- `PATCH /v1/issuer/schemas/{id}` — [Update a draft credential schema](https://aho.com/docs/api/credential-schemas/update.md)
- `DELETE /v1/issuer/schemas/{id}` — [Delete a draft credential schema](https://aho.com/docs/api/credential-schemas/delete.md)
- `POST /v1/issuer/schemas/{id}/activate` — [Activate a draft credential schema](https://aho.com/docs/api/credential-schemas/activate.md)
- `POST /v1/issuer/schemas/{id}/archive` — [Archive an active credential schema](https://aho.com/docs/api/credential-schemas/archive.md)

### [Data Sources](https://aho.com/docs/api/data-sources.md)

connect to external systems that contain subject data for automated credential issuance.

Supported source types:
- **PostgreSQL**: Connect to a database to query employee/student/member records
- **CSV**: Upload files for batch processing

Data sources store encrypted connection credentials and can be tested before activation.
Use data sources with Data Source Mappings and Automations to issue credentials automatically.

- `GET /v1/issuer/data_sources` — [List data sources](https://aho.com/docs/api/data-sources/list.md)
- `GET /v1/issuer/data_sources/{id}` — [Get data source details](https://aho.com/docs/api/data-sources/get.md)
- `POST /v1/issuer/data_sources` — [Create a data source](https://aho.com/docs/api/data-sources/create.md)
- `PATCH /v1/issuer/data_sources/{id}` — [Update a data source](https://aho.com/docs/api/data-sources/update.md)
- `DELETE /v1/issuer/data_sources/{id}` — [Delete a data source](https://aho.com/docs/api/data-sources/delete.md)
- `POST /v1/issuer/data_sources/{id}/test` — [Test data source connection](https://aho.com/docs/api/data-sources/test.md)

### [Data Source Mappings](https://aho.com/docs/api/data-source-mappings.md)

define how data from a source translates into credential claims.

A mapping connects:
- A **Data Source** (where to get the data)
- A **Credential Schema** (what credential to issue)
- **Field Mappings** (which source columns map to which credential claims)
- **Query Configuration** (how to extract records from the source)

Example: Map the "full_name" database column to the "name" credential claim.

- `GET /v1/issuer/data_source_mappings` — [List data source mappings](https://aho.com/docs/api/data-source-mappings/list.md)
- `GET /v1/issuer/data_source_mappings/{id}` — [Get mapping details](https://aho.com/docs/api/data-source-mappings/get.md)
- `POST /v1/issuer/data_source_mappings` — [Create a data source mapping](https://aho.com/docs/api/data-source-mappings/create.md)
- `PATCH /v1/issuer/data_source_mappings/{id}` — [Update a mapping](https://aho.com/docs/api/data-source-mappings/update.md)
- `DELETE /v1/issuer/data_source_mappings/{id}` — [Delete a mapping](https://aho.com/docs/api/data-source-mappings/delete.md)

### [Automations](https://aho.com/docs/api/automations.md)

run credential issuance workflows automatically based on triggers.

Trigger modes:
- **Manual**: Triggered via API call or dashboard button
- **Scheduled**: Runs on a cron schedule (e.g., daily at midnight)
- **Webhook**: Triggered by external systems via webhook URL

Each automation uses a Data Source Mapping to know what data to fetch and what credentials to issue.
Automations can be paused, resumed, and monitored for run history.

- `GET /v1/issuer/automations` — [List automations](https://aho.com/docs/api/automations/list.md)
- `GET /v1/issuer/automations/{id}` — [Get automation details](https://aho.com/docs/api/automations/get.md)
- `POST /v1/issuer/automations` — [Create an automation](https://aho.com/docs/api/automations/create.md)
- `PATCH /v1/issuer/automations/{id}` — [Update an automation](https://aho.com/docs/api/automations/update.md)
- `DELETE /v1/issuer/automations/{id}` — [Delete an automation](https://aho.com/docs/api/automations/delete.md)
- `POST /v1/issuer/automations/{automation_id}/webhook` — [Generate webhook token](https://aho.com/docs/api/automations/create_webhook.md)
- `DELETE /v1/issuer/automations/{automation_id}/webhook` — [Revoke webhook token](https://aho.com/docs/api/automations/delete_webhook.md)
- `GET /v1/issuer/automations/{automation_id}/webhook` — [Get webhook configuration](https://aho.com/docs/api/automations/get_webhook.md)
- `POST /v1/issuer/automations/{id}/pause` — [Pause an automation](https://aho.com/docs/api/automations/pause.md)
- `POST /v1/issuer/automations/{id}/resume` — [Resume an automation](https://aho.com/docs/api/automations/resume.md)
- `POST /v1/issuer/automations/{id}/trigger` — [Trigger an automation](https://aho.com/docs/api/automations/trigger.md)

### [Credential Issuances](https://aho.com/docs/api/credential-issuances.md)

are the verifiable credentials you issue to holders.

Operations:
- Issue new credentials (directly or via credential offers)
- List and search issued credentials
- Revoke or suspend credentials
- Check credential status

Credentials are cryptographically signed using your signing keys and can be verified by anyone.

- `GET /v1/issuer/credentials` — [List credentials](https://aho.com/docs/api/credential-issuances/list.md)
- `GET /v1/issuer/credentials/{uuid}` — [Get issued credential details](https://aho.com/docs/api/credential-issuances/get.md)
- `POST /v1/issuer/credentials` — [Issue a new credential](https://aho.com/docs/api/credential-issuances/create.md)
- `GET /v1/issuer/credentials/{uuid}/history` — [Get credential history](https://aho.com/docs/api/credential-issuances/history.md)
- `POST /v1/issuer/credentials/{uuid}/reinstate` — [Reinstate a suspended credential](https://aho.com/docs/api/credential-issuances/reinstate.md)
- `POST /v1/issuer/credentials/reinstate_batch` — [Reinstate multiple credentials](https://aho.com/docs/api/credential-issuances/reinstate_batch.md)
- `POST /v1/issuer/credentials/{uuid}/revoke` — [Revoke a credential](https://aho.com/docs/api/credential-issuances/revoke.md)
- `POST /v1/issuer/credentials/revoke_batch` — [Revoke multiple credentials](https://aho.com/docs/api/credential-issuances/revoke_batch.md)
- `GET /v1/issuer/credentials/{uuid}/status` — [Get credential status](https://aho.com/docs/api/credential-issuances/status.md)
- `POST /v1/issuer/credentials/{uuid}/suspend` — [Suspend a credential](https://aho.com/docs/api/credential-issuances/suspend.md)
- `POST /v1/issuer/credentials/suspend_batch` — [Suspend multiple credentials](https://aho.com/docs/api/credential-issuances/suspend_batch.md)

### [Credential Offers](https://aho.com/docs/api/credential-offers.md)

let holders claim credentials through a wallet app using OpenID4VCI protocol.

Flow:
1. Create an offer with the credential data
2. Share the offer URL or QR code with the holder
3. Holder scans/clicks and their wallet fetches the credential

Offers can be one-time use or reusable, with optional PIN protection.

- `GET /v1/issuer/offers` — [List credential offers](https://aho.com/docs/api/credential-offers/list.md)
- `GET /v1/issuer/offers/{uuid}` — [Get credential offer details](https://aho.com/docs/api/credential-offers/get.md)
- `POST /v1/issuer/offers` — [Create a credential offer](https://aho.com/docs/api/credential-offers/create.md)
- `POST /v1/issuer/offers/{uuid}/revoke` — [Revoke a credential offer](https://aho.com/docs/api/credential-offers/revoke.md)

### [Credential Verification](https://aho.com/docs/api/credential-verification.md)

validates credentials and checks their authenticity.

Verification checks:
- Cryptographic signature validity
- Expiration status
- Revocation/suspension status
- Issuer trust signals (domain verification, organization info)

Use this to verify credentials presented to you before trusting their claims.

- `GET /v1/issuer/verify/{uuid}` — [Verify a credential by UUID](https://aho.com/docs/api/credential-verification/get.md)
- `POST /v1/issuer/verify` — [Verify a credential](https://aho.com/docs/api/credential-verification/create.md)

### [Presentation Requests](https://aho.com/docs/api/presentation-requests.md)

ask holders to present specific credentials using OpenID4VP protocol.

Define what credentials you need:
- Required credential types
- Required claims within those credentials
- Optional constraints (issuer, expiration, etc.)

Requests generate a URL/QR code that holders scan to share matching credentials from their wallet.

- `GET /v1/verifier/requests` — [List presentation requests](https://aho.com/docs/api/presentation-requests/list.md)
- `GET /v1/verifier/requests/{uuid}` — [Get presentation request details](https://aho.com/docs/api/presentation-requests/get.md)
- `POST /v1/verifier/requests` — [Create a presentation request](https://aho.com/docs/api/presentation-requests/create.md)
- `PATCH /v1/verifier/requests/{uuid}` — [Update a draft presentation request](https://aho.com/docs/api/presentation-requests/update.md)
- `DELETE /v1/verifier/requests/{uuid}` — [Delete a draft presentation request](https://aho.com/docs/api/presentation-requests/delete.md)
- `POST /v1/verifier/requests/{uuid}/activate` — [Activate a draft presentation request](https://aho.com/docs/api/presentation-requests/activate.md)
- `POST /v1/verifier/requests/{uuid}/close` — [Close an active presentation request](https://aho.com/docs/api/presentation-requests/close.md)
- `GET /v1/verifier/requests/{uuid}/qr_code` — [Get QR code for presentation request](https://aho.com/docs/api/presentation-requests/qr_code.md)

### [Presentation Responses](https://aho.com/docs/api/presentation-responses.md)

contain the credentials holders submit in response to your requests.

After a holder responds to a presentation request, retrieve and verify the submitted credentials here.
Responses include the raw credential data and verification status.

- `GET /v1/verifier/requests/{request_uuid}/responses` — [List responses for a presentation request](https://aho.com/docs/api/presentation-responses/list.md)
- `GET /v1/verifier/requests/{request_uuid}/responses/{uuid}` — [Get response details](https://aho.com/docs/api/presentation-responses/get.md)

### [DC API Sessions](https://aho.com/docs/api/dc-api-sessions.md)

enable server-to-server verification using the Digital Credentials API.

The thin client architecture keeps credential handling server-side:
1. Create a session to get encryption keys and request configs
2. Your frontend uses the Digital Credentials API to request credentials
3. POST the encrypted response back to verify and extract claims

Benefits:
- No credential data exposed to frontend JavaScript
- Cryptographic binding via session transcript
- Works with Chrome/Android (OpenID4VP) and Safari/iOS (mdoc)

Sessions expire after 5 minutes and are single-use.

- `GET /v1/verifier/dc_sessions/{id}/render` — [Render verified claims as visual credential](https://aho.com/docs/api/dc-api-sessions/list.md)
- `GET /v1/verifier/dc_sessions/{id}` — [Get DC API session status](https://aho.com/docs/api/dc-api-sessions/get.md)
- `POST /v1/verifier/dc_sessions` — [Create a DC API session](https://aho.com/docs/api/dc-api-sessions/create.md)
- `POST /v1/verifier/dc_sessions/{id}/verify` — [Verify a DC API session](https://aho.com/docs/api/dc-api-sessions/verify.md)

### [Credentials](https://aho.com/docs/api/credentials.md)

are credentials owned by an end user (holder).

Operations:
- List credentials in the holder's wallet
- View credential details and claims
- Delete credentials from the wallet

Holders receive credentials through credential offers or direct issuance.

- `GET /v1/holder/credentials` — [List holder credentials](https://aho.com/docs/api/credentials/list.md)
- `GET /v1/holder/credentials/{uuid}` — [Get holder credential details](https://aho.com/docs/api/credentials/get.md)

### [Presentations](https://aho.com/docs/api/presentations.md)

are packaged credentials that holders share with verifiers.

Create verifiable presentations to respond to verification requests,
proving you hold certain credentials without revealing unnecessary information.

- `GET /v1/holder/presentations` — [List holder presentations](https://aho.com/docs/api/presentations/list.md)
- `GET /v1/holder/presentations/{uuid}` — [Get presentation details](https://aho.com/docs/api/presentations/get.md)
- `POST /v1/holder/presentations` — [Create a credential presentation](https://aho.com/docs/api/presentations/create.md)
- `DELETE /v1/holder/presentations/{uuid}` — [Revoke a presentation](https://aho.com/docs/api/presentations/delete.md)
- `POST /v1/verifier/presentations/verify` — [Verify a presentation](https://aho.com/docs/api/presentations/verify.md)

### [Domains](https://aho.com/docs/api/domains.md)

establish your organization's identity for credential issuance.

Your domain becomes part of your DID (Decentralized Identifier): `did:web:yourdomain.com`

Domain verification:
1. Add your domain
2. Create the required DNS TXT record
3. Verify ownership

A verified domain increases trust in your issued credentials.

- `GET /v1/account/domains` — [List domains](https://aho.com/docs/api/domains/list.md)
- `GET /v1/account/domains/{id}` — [Get domain details](https://aho.com/docs/api/domains/get.md)
- `POST /v1/account/domains` — [Register a domain](https://aho.com/docs/api/domains/create.md)
- `DELETE /v1/account/domains/{id}` — [Delete a domain](https://aho.com/docs/api/domains/delete.md)
- `POST /v1/account/domains/{id}/verify` — [Verify domain](https://aho.com/docs/api/domains/verify.md)

### [Signing Keys](https://aho.com/docs/api/signing-keys.md)

are the cryptographic keys used to sign your verifiable credentials.

Key features:
- Keys are generated and stored securely (never exposed)
- Support for key rotation with overlap periods
- Multiple algorithms supported (ES256, EdDSA)

Each credential is signed with your active key, allowing verifiers to confirm authenticity.

- `GET /v1/account/signing_keys` — [List signing keys](https://aho.com/docs/api/signing-keys/list.md)
- `GET /v1/account/signing_keys/{id}` — [Get signing key details](https://aho.com/docs/api/signing-keys/get.md)
- `POST /v1/account/signing_keys` — [Generate a signing key](https://aho.com/docs/api/signing-keys/create.md)
- `GET /v1/account/signing_keys/{id}/certificate` — [Download X.509 certificate](https://aho.com/docs/api/signing-keys/certificate.md)
- `POST /v1/account/signing_keys/{id}/revoke` — [Revoke a signing key](https://aho.com/docs/api/signing-keys/revoke.md)
- `POST /v1/account/signing_keys/{id}/rotate` — [Rotate a signing key](https://aho.com/docs/api/signing-keys/rotate.md)

### [API Keys](https://aho.com/docs/api/api-keys.md)

authenticate your API requests.

Each account has two types of keys:
- **Secret Key**: For server-to-server API calls. Never expose in client-side code.
- **Publishable Key**: For browser-based requests. Restricted by origin allowlist.

Keys auto-create on first access and can be regenerated if compromised (old value stops working immediately).

- `GET /v1/account/api_keys` — [List API keys](https://aho.com/docs/api/api-keys/list.md)
- `GET /v1/account/api_keys/{hashid}` — [Get API key details](https://aho.com/docs/api/api-keys/get.md)
- `POST /v1/account/api_keys/{hashid}/regenerate` — [Regenerate API key](https://aho.com/docs/api/api-keys/create.md)
- `PATCH /v1/account/api_keys/{hashid}` — [Update API key](https://aho.com/docs/api/api-keys/update.md)

### [Webhooks](https://aho.com/docs/api/webhooks.md)

notify your systems when events occur in your account.

Supported events:
- Credential issued, revoked, suspended
- Presentation request completed
- Domain verification status changes

Configure a webhook URL to receive real-time event notifications with cryptographic signatures for verification.

- `GET /v1/account/webhooks` — [List webhooks](https://aho.com/docs/api/webhooks/list.md)
- `GET /v1/account/webhooks/primary` — [Get webhook details](https://aho.com/docs/api/webhooks/get.md)
- `POST /v1/account/webhooks` — [Create webhook](https://aho.com/docs/api/webhooks/create.md)
- `PATCH /v1/account/webhooks/primary` — [Update webhook](https://aho.com/docs/api/webhooks/update.md)
- `DELETE /v1/account/webhooks/primary` — [Delete webhook](https://aho.com/docs/api/webhooks/delete.md)
- `POST /v1/account/webhooks/primary/test` — [Test webhook](https://aho.com/docs/api/webhooks/test.md)

### [Hooks](https://aho.com/docs/api/hooks.md)

allow external systems to trigger actions without API key authentication.

Currently supports:
- **Automation triggers**: External systems POST to trigger credential automation runs

Each trigger uses a unique token URL. Tokens can be regenerated if compromised.

### [Schemas](https://aho.com/docs/api/schemas.md)

provides read-only access to credential schemas.

Anyone can browse available credential types and their claim structures.
No authentication required.

- `GET /v1/schemas` — [Browse public credential schemas](https://aho.com/docs/api/schemas/list.md)
- `GET /v1/schemas/{slug}` — [Get schema details](https://aho.com/docs/api/schemas/get.md)

### [Render Templates](https://aho.com/docs/api/render-templates.md)

define how credentials are visually displayed.

Templates use Liquid syntax to generate SVG or HTML representations
of credentials for display in wallets, emails, or print.

- `GET /v1/schemas/{schema_id}/render_templates` — [List render templates](https://aho.com/docs/api/render-templates/list.md)
- `GET /v1/schemas/{schema_id}/render_templates/{id}` — [Get render template](https://aho.com/docs/api/render-templates/get.md)
- `POST /v1/schemas/{schema_id}/render_templates` — [Create render template](https://aho.com/docs/api/render-templates/create.md)
- `PATCH /v1/schemas/{schema_id}/render_templates/{id}` — [Update render template](https://aho.com/docs/api/render-templates/update.md)
- `DELETE /v1/schemas/{schema_id}/render_templates/{id}` — [Delete render template](https://aho.com/docs/api/render-templates/delete.md)
- `POST /v1/schemas/{schema_id}/render_templates/validate` — [Validate template](https://aho.com/docs/api/render-templates/validate.md)

### [System](https://aho.com/docs/api/system.md)

Health check and system status endpoints.

- `GET /v1/health` — [Health check](https://aho.com/docs/api/system/get.md)