Core API

Verification & Consent

Verification proves control of an alias or endpoint. Consent grants let an identity disclose sensitive endpoints to a specific consumer — scoped, revocable, and time-boxed.

Proof of control

Before an alias or endpoint is treated as trustworthy, the owner proves control via a one-time-passcode challenge. This is not KYC of a person — Settla records control of an identifier, not regulated identity verification.

Start a challenge

POST/v1/verify-alias

Scope: verifications:write.

Field	Type	Description
`alias_id`optional	`string`	The alias to verify (`als_…`). Provide this or `endpoint_id`.
`endpoint_id`optional	`string`	The endpoint to verify (`end_…`).
`method`optional	`string`	Challenge method, e.g. `otp` (sent to the alias/endpoint channel).

curl https://api.settla.network/v1/verify-alias \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "alias_id": "als_...", "method": "otp" }'
# dev/test responses include a dev_code; live sends the OTP out-of-band
# => { "id": "vrf_...", "status": "pending", "dev_code": "418204" }

Dev shortcut

Outside live, verification responses include a dev_code and the magic code 000000 is always accepted, so you can complete the flow without a real channel.

Confirm the challenge

POST/v1/verifications/:id/confirm

Submit the code. On success the subject becomes active and an alias.verified / endpoint.verified event is emitted. Verified aliases/endpoints feed the verified-merchant badge and trust score.

curl https://api.settla.network/v1/verifications/vrf_.../confirm \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "code": "418204" }'
# on success the subject (alias or endpoint) becomes active
# => { "id": "vrf_...", "status": "verified" }

Endpoints with privacy level consent_required are disclosed only when a valid ConsentGrant (cgr_…) exists for that consumer ↔ identity. This is how a business shares a payout endpoint with one partner without making it public.

POST/v1/consent-grants

Scope: consent:write.

Field	Type	Description
`identity`required	`string`	Whose endpoints the grant covers (idn_…).
`api_consumer`required	`string`	Which consumer (apc_…) may resolve them.
`scope`required	`string`	`resolve_basic` (alias gate), `disclose_endpoint` (specific endpoints), or `disclose_endpoint_type` (a typed subset).
`endpoint_ids`optional	`string[]`	Specific endpoints, required for `disclose_endpoint`.
`endpoint_type`optional	`string`	A type, used with `disclose_endpoint_type`.
`expires_at`optional	`string (ISO 8601)`	Time-box the grant. Expired grants disclose nothing.

curl https://api.settla.network/v1/consent-grants \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "idn_2x9...",
    "api_consumer": "apc_partner...",
    "scope": "disclose_endpoint",
    "endpoint_ids": ["end_b2..."],
    "expires_at": "2026-12-31T00:00:00Z"
  }'

Lifecycle

State	Behavior
pending	Requested; owner is notified. No disclosure yet.
active	Disclosure permitted within the grant's scope and expiry.
revoked	Owner revoked it; takes effect on the next resolution (fail-closed).
expired	Past expires_at; auto-expires, no auto-renew.
invalidated	The endpoint was removed or the identity deactivated.

Manage grants:

GET/v1/identities/:id/consent-grants

DELETE/v1/consent-grants/:id

Minimal disclosure, fail-closed

Default to the narrowest grant: per-endpoint, per-consumer, expiring. If consent state is unavailable or uncertain, the endpoint is omitted — never disclosed by default. Every grant/approve/deny/revoke/expire is audited. See Privacy & Security.