Skip to main content

​
Authentication

Signing endpoints split into two groups based on how they authenticate:
GroupAuth methodUse case
App endpointsclientId + clientSecret in bodyServer-to-server, creating requests on behalf of users
Session endpointsAuthorization: Bearer AVE_SESSION_TOKENAuthenticated Ave user managing their own keys and requests

​
App endpoints

​
POST /api/signing/request

Creates a signature request for a specific identity. Call this from your server — never from the browser. Request body:
​
clientId
string
required
Your app’s client ID.
​
clientSecret
string
required
Your app’s client secret.
​
identityId
string
required
UUID of the Ave identity that will sign the request. This is the sub claim from the user’s id_token. The identity must have a signing key set up.
​
payload
string
required
The string the user will see and sign. Keep it human-readable. Maximum 10,000 characters.
​
metadata
object
Arbitrary JSON metadata attached to the request. Not shown to the user in the signing UI but persisted with the record.
​
expiresInSeconds
number
default:"300"
How long the request stays active before expiring. Minimum 60, maximum 3600.
Response:
​
requestId
string
UUID for this signing request. Use it to present the signing UI and poll for status.
​
expiresAt
string
ISO 8601 timestamp when the request expires.
​
publicKey
string
Ed25519 public key for this identity in base64. Store it if you want to verify signatures locally.
Example: 
POST https://api.aveid.net/api/signing/request
Content-Type: application/json

{
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "identityId": "identity-uuid",
  "payload": "I approve the transfer of $500 to account ending 4242",
  "metadata": { "action": "transfer", "amount": 500 },
  "expiresInSeconds": 300
}
Error responses:
StatusErrorCause
400invalid_requestMissing required field
401invalid_clientclientId or clientSecret mismatch
404identity_not_foundidentityId does not exist
422no_signing_keyIdentity has not set up a signing key

​
GET /api/signing/request/:requestId/status

Returns the current status of a signing request. Query parameters:
​
clientId
string
required
Your app’s client ID. Only requests belonging to this app are accessible.
Response:
​
status
string
Current state: pending, signed, denied, or expired.If the request has passed its expiresAt timestamp and is still pending, the server automatically transitions it to expired when this endpoint is queried.
​
signature
string
The Ed25519 signature in base64. Present only when status is signed.
​
resolvedAt
string
ISO 8601 timestamp when the request was resolved. Present when status is signed or denied.
Example: 
GET https://api.aveid.net/api/signing/request/req-uuid/status?clientId=YOUR_CLIENT_ID
Error responses:
StatusCause
403Request does not belong to the provided clientId
404Request not found

​
GET /api/signing/public-key/:handle

Returns the Ed25519 public key for an identity by its handle (username). Use this to verify signatures independently without calling the verify endpoint. Path parameters:
​
handle
string
required
The identity’s handle (username, without @).
Response:
​
handle
string
The identity handle.
​
publicKey
string
Ed25519 public key in base64.
​
createdAt
string
When the signing key was created.
Error responses:
StatusCause
404Identity not found
404Identity has no signing key

​
POST /api/signing/verify

Verifies a message/signature/publicKey tuple. Use this as a server-side verification step before executing any side effect triggered by a signature. Request body:
​
message
string
required
The signed payload string, exactly as it appeared in the signing request.
​
signature
string
required
The Ed25519 signature in base64, from the signed request status response.
​
publicKey
string
required
The Ed25519 public key in base64, from the create request response or public key endpoint.
Response:
​
valid
boolean
true if the signature is cryptographically valid for the message and key. false otherwise.
​
error
string
Present when valid is false. Describes why verification failed.
Example: 
POST https://api.aveid.net/api/signing/verify
Content-Type: application/json

{
  "message": "I approve the transfer of $500 to account ending 4242",
  "signature": "base64-ed25519-signature",
  "publicKey": "base64-ed25519-public-key"
}
You can also verify signatures locally using any Ed25519 library without calling this endpoint. Use the publicKey from the create request response, the signature from the status response, and the original payload string.

​
Session-authenticated endpoints

These endpoints require an Ave session token in the Authorization header. They are used by authenticated Ave users to manage their own signing keys and view/act on signing requests. 
Authorization: Bearer AVE_SESSION_TOKEN

​
Key management

Returns all signing keys for the authenticated user’s identities.
Returns the signing key for a specific identity owned by the authenticated user. Returns 404 if the identity has no signing key or does not belong to the user.
Creates a signing key for the specified identity. The identity must belong to the authenticated user and must not already have a signing key.
Rotates (replaces) the signing key for the specified identity.

​
Request interaction

Returns pending signing requests for the authenticated user’s identities.
Returns details of a specific signing request targeted at the authenticated user.
Signs the request. Identity ownership is enforced. Request must be in pending state. The server validates the cryptographic signature format before accepting.
Denies the request. Request must be in pending state.

​
Demo endpoint

POST /api/signing/demo/request creates a signing request without app credentials. It is reserved for the Ave playground and demo tooling. Do not use in production integrations.
Last modified on March 3, 2026