Create a decentralised identifier for an organization
POST/api/v1/identifiers
Requires Idempotency-Key. Names an organization inside the caller scope; the issuance module reads the organization itself and takes nothing else about it from the body. An organization may hold one identifier that has not failed: a second is refused with 409 and code identifier.exists.
Two methods exist. webvh, the default, publishes a signed, append-only log: every change is an entry chained to the one before, so a verifier can tell a key rotation from a substitution, and the next update key is committed in advance, so a lost key does not freeze the identifier. web publishes one replaceable document with no history and no recovery, and whoever controls the domain can replace it; choose it only for verifiers that resolve nothing else. A webvh identifier is also served in did:web form beside its log, so it rarely needs choosing. The method is fixed at creation, and a deployment may not permit web, in which case asking for it is refused with 400 and code identifier.method_not_permitted, at body.method.
The answer is 202 and the identifier in state placing: its keys are generated and its document rendered just after this reply, once the organization has been placed on an agent. Read the identifier at the Location given until it is prepared, then preview it and publish it. Nothing is published by creating.
host serves the identifier on a delegated host instead of the organization's own publisher host. Its DNS must already point at the platform: that is checked at every publication, which is refused with 409 and code identifier.host_unverified while the name resolves elsewhere; correct the DNS record and publish again. A name that is an address, or that sits under the platform's own domains anywhere but beneath the organization's own, is refused with 400 and code identifier.host_refused, at body.host. Without host, the organization's own publisher host is used, and when another identifier already serves that host the answer is 409 with code identifier.host_taken; the answer never says whose.
Request
Responses
- 202
- 400
- 401
- 403
- 404
- 409
- 415
- 429
- 500
- 502
- 503
The identifier, in state placing. Read it again.
Response Headers
The correlation id of the request, on every response including 401.
Where to read the identifier: /api/v1/identifiers/{id}.
The request is malformed. callerShould: fix-and-retry.
Response Headers
The correlation id of the request, on every response including 401.
Authentication is required. callerShould: authenticate.
Response Headers
The correlation id of the request, on every response including 401.
The token is valid but maps to no usable principal. callerShould: stop.
Response Headers
The correlation id of the request, on every response including 401.
The resource was not found. The same answer for a subject that does not exist and one outside the caller's scope. callerShould: stop.
Response Headers
The correlation id of the request, on every response including 401.
The resource is not in a state that allows this (callerShould: re-read-and-decide), or A concurrent change conflicted with this request (callerShould: re-read-and-retry-once). Told apart by the type URI; the code member names the refusal (for example subject.slug_taken). A conflict the module marked not retryable carries callerShould: re-read-and-decide.
Response Headers
The correlation id of the request, on every response including 401.
The request body has an unsupported media type. Send application/json. callerShould: fix-and-retry.
Response Headers
The correlation id of the request, on every response including 401.
Too many requests. The rate limit for this caller was reached: 600 a minute per authenticated principal, 60 a minute per client address before authentication (both configurable). callerShould: retry-with-backoff, after the number of seconds in Retry-After.
Response Headers
The correlation id of the request, on every response including 401.
Whole seconds to wait before the next request.
An internal error occurred. callerShould: retry-with-backoff.
Response Headers
The correlation id of the request, on every response including 401.
A system we depend on failed. callerShould: retry-with-backoff.
Response Headers
The correlation id of the request, on every response including 401.
The service cannot serve this right now. callerShould: retry-with-backoff.
Response Headers
The correlation id of the request, on every response including 401.