> For the complete documentation index, see [llms.txt](https://docs.meeco.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.meeco.me/openapi-docs/svx-api/admin-authentication.md).
# Admin Authentication
## List admin accounts
> Lists all registered admin accounts.
```json
{"openapi":"3.1.0","info":{"title":"SVX Wallet API","version":"4.0.1"},"servers":[{"url":"https://zyfla-wallet-sandbox.meeco.cloud","description":"SVX Wallet deployment (relative)"}],"security":[{},{"bearerAuth":[]},{"mutualTLS":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","scheme":"bearer","type":"http"},"mutualTLS":{"type":"mutualTLS"}},"schemas":{"ListAdminAccountsResponseDto":{"type":"object","properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/AdminAccountDto"}}},"required":["accounts"]},"AdminAccountDto":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"Admin account identifier."},"display_name":{"type":"string","description":"Optional admin display name."},"invitation_accepted_at":{"type":"string","format":"date-time","description":"Timestamp when invitation was accepted (ISO 8601 UTC)."},"created_at":{"type":"string","format":"date-time","description":"Account creation timestamp (ISO 8601 UTC)."},"updated_at":{"type":"string","format":"date-time","description":"Last account update timestamp (ISO 8601 UTC)."},"passkeys_count":{"type":"integer","description":"Number of registered passkeys for this account."}},"required":["account_id","display_name","invitation_accepted_at","created_at","updated_at","passkeys_count"]}}},"paths":{"/admin/accounts":{"get":{"summary":"List admin accounts","description":"Lists all registered admin accounts.\n","operationId":"AdminAuthController_listAccounts","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAdminAccountsResponseDto"}}},"description":"Accounts list retrieved"}},"tags":["Admin Authentication"]}}}}
```
## Delete admin account
> Deletes a registered admin account and related passkeys.
```json
{"openapi":"3.1.0","info":{"title":"SVX Wallet API","version":"4.0.1"},"servers":[{"url":"https://zyfla-wallet-sandbox.meeco.cloud","description":"SVX Wallet deployment (relative)"}],"security":[{},{"bearerAuth":[]},{"mutualTLS":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","scheme":"bearer","type":"http"},"mutualTLS":{"type":"mutualTLS"}},"schemas":{"DeleteAdminAccountResponseDto":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"Identifier of the deleted admin account."},"deleted":{"type":"boolean","description":"Always `true` when deletion succeeds."}},"required":["account_id","deleted"]},"AdminPasskeyErrorResponseDto":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"extra_info":{"type":"object","additionalProperties":true}},"required":["error","message","extra_info"]}}},"paths":{"/admin/accounts/{id}":{"delete":{"summary":"Delete admin account","description":"Deletes a registered admin account and related passkeys.\n","operationId":"AdminAuthController_deleteAccount","parameters":[{"name":"id","required":true,"in":"path","description":"ID of the admin account to delete","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteAdminAccountResponseDto"}}},"description":"Account deleted"},"404":{"description":"Account was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPasskeyErrorResponseDto"}}}}},"tags":["Admin Authentication"]}}}}
```
## List admin invitations
> Lists all pending, non-expired admin invitations.
```json
{"openapi":"3.1.0","info":{"title":"SVX Wallet API","version":"4.0.1"},"servers":[{"url":"https://zyfla-wallet-sandbox.meeco.cloud","description":"SVX Wallet deployment (relative)"}],"security":[{},{"bearerAuth":[]},{"mutualTLS":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","scheme":"bearer","type":"http"},"mutualTLS":{"type":"mutualTLS"}},"schemas":{"ListAdminInvitationsResponseDto":{"type":"object","properties":{"invitations":{"type":"array","items":{"$ref":"#/components/schemas/AdminInvitationDto"}}},"required":["invitations"]},"AdminInvitationDto":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"Invitation/account identifier."},"display_name":{"type":"string","description":"Optional display name captured at invitation creation time."},"expires_at":{"type":"string","format":"date-time","description":"Invitation expiration timestamp (ISO 8601 UTC)."},"created_at":{"type":"string","format":"date-time","description":"Invitation creation timestamp (ISO 8601 UTC)."}},"required":["account_id","display_name","expires_at","created_at"]}}},"paths":{"/admin/invitations":{"get":{"summary":"List admin invitations","description":"Lists all pending, non-expired admin invitations.\n","operationId":"AdminAuthController_listInvitations","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAdminInvitationsResponseDto"}}},"description":"Invitations list retrieved"}},"tags":["Admin Authentication"]}}}}
```
## Create admin passkey invitation
> Creates an invitation token that can be used exactly once to register the first admin passkey.
```json
{"openapi":"3.1.0","info":{"title":"SVX Wallet API","version":"4.0.1"},"servers":[{"url":"https://zyfla-wallet-sandbox.meeco.cloud","description":"SVX Wallet deployment (relative)"}],"security":[{},{"bearerAuth":[]},{"mutualTLS":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","scheme":"bearer","type":"http"},"mutualTLS":{"type":"mutualTLS"}},"schemas":{"CreateAdminInvitationRequestDto":{"type":"object","properties":{"display_name":{"type":"string","maxLength":255,"description":"Optional display name to associate with the invitation and resulting admin account."}}},"CreateAdminInvitationResponseDto":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"Identifier of the invitation/account record."},"secret_token":{"type":"string","description":"One-time invitation secret token to be used in registration endpoints."},"expires_at":{"type":"string","format":"date-time","description":"Invitation expiration timestamp (ISO 8601 UTC)."}},"required":["account_id","secret_token","expires_at"]}}},"paths":{"/admin/invitations":{"post":{"summary":"Create admin passkey invitation","description":"Creates an invitation token that can be used exactly once to register the first admin passkey.\n","operationId":"AdminAuthController_createInvitation","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAdminInvitationRequestDto"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAdminInvitationResponseDto"}}},"description":"Admin passkey invitation created"}},"tags":["Admin Authentication"]}}}}
```
## Delete admin invitation
> Deletes a pending admin invitation.
```json
{"openapi":"3.1.0","info":{"title":"SVX Wallet API","version":"4.0.1"},"servers":[{"url":"https://zyfla-wallet-sandbox.meeco.cloud","description":"SVX Wallet deployment (relative)"}],"security":[{},{"bearerAuth":[]},{"mutualTLS":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","scheme":"bearer","type":"http"},"mutualTLS":{"type":"mutualTLS"}},"schemas":{"DeleteAdminInvitationResponseDto":{"type":"object","properties":{"invitation_id":{"type":"string","format":"uuid","description":"Identifier of the deleted invitation."},"deleted":{"type":"boolean","description":"Always `true` when deletion succeeds."}},"required":["invitation_id","deleted"]},"AdminPasskeyErrorResponseDto":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"extra_info":{"type":"object","additionalProperties":true}},"required":["error","message","extra_info"]}}},"paths":{"/admin/invitations/{id}":{"delete":{"summary":"Delete admin invitation","description":"Deletes a pending admin invitation.\n","operationId":"AdminAuthController_deleteInvitation","parameters":[{"name":"id","required":true,"in":"path","description":"ID of the admin invitation to delete","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteAdminInvitationResponseDto"}}},"description":"Invitation deleted"},"404":{"description":"Invitation was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPasskeyErrorResponseDto"}}}}},"tags":["Admin Authentication"]}}}}
```
## Start admin passkey registration
> Starts WebAuthn registration for a pending invitation and returns \`PublicKeyCredentialCreationOptionsJSON\`.\
> \
> Use the returned \`options\` with \`navigator.credentials.create(...)\`, then submit the resulting credential to\
> \`/admin/invitations/accept\` together with \`challenge\_id\`.
```json
{"openapi":"3.1.0","info":{"title":"SVX Wallet API","version":"4.0.1"},"servers":[{"url":"https://zyfla-wallet-sandbox.meeco.cloud","description":"SVX Wallet deployment (relative)"}],"security":[],"paths":{"/admin/invitations/accept/options":{"post":{"summary":"Start admin passkey registration","description":"Starts WebAuthn registration for a pending invitation and returns `PublicKeyCredentialCreationOptionsJSON`.\n\nUse the returned `options` with `navigator.credentials.create(...)`, then submit the resulting credential to\n`/admin/invitations/accept` together with `challenge_id`.\n","operationId":"AdminAuthController_startInvitationRegistration","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartAdminPasskeyRegistrationRequestDto"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartAdminPasskeyRegistrationOptionsResponseDto"}}},"description":"Registration options generated"},"400":{"description":"Invitation is expired or invalid request data was provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPasskeyErrorResponseDto"}}}},"404":{"description":"Invitation was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPasskeyErrorResponseDto"}}}},"409":{"description":"Invitation has already been used","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPasskeyErrorResponseDto"}}}}},"tags":["Admin Authentication"]}}},"components":{"schemas":{"StartAdminPasskeyRegistrationRequestDto":{"type":"object","properties":{"secret_token":{"type":"string","description":"Invitation secret token returned by `/admin/invitations`."}},"required":["secret_token"]},"StartAdminPasskeyRegistrationOptionsResponseDto":{"type":"object","properties":{"challenge_id":{"type":"string","format":"uuid","description":"Challenge identifier required by `/admin/invitations/accept`."},"options":{"type":"object","additionalProperties":true,"description":"WebAuthn `PublicKeyCredentialCreationOptionsJSON` payload to pass to `navigator.credentials.create({ publicKey: options })`.\n\nCommon fields:\n- `challenge`: Base64URL challenge generated by the server.\n- `rp`: Relying Party metadata (`id`, `name`).\n- `user`: User handle and display metadata (`id`, `name`, `displayName`).\n- `pubKeyCredParams`: Supported public key algorithms.\n- `timeout`: Timeout in milliseconds.\n- `attestation`: Attestation conveyance preference.\n- `authenticatorSelection`: Authenticator requirements/preferences.\n- `excludeCredentials`: Credentials that must not be re-registered.\n"}},"required":["challenge_id","options"]},"AdminPasskeyErrorResponseDto":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"extra_info":{"type":"object","additionalProperties":true}},"required":["error","message","extra_info"]}}}}
```
## Verify admin passkey registration
> Verifies the WebAuthn registration response produced by \`navigator.credentials.create(...)\` and persists\
> the admin passkey.\
> \
> \`challenge\_id\` must match the value returned by \`/admin/invitations/accept/options\`.
```json
{"openapi":"3.1.0","info":{"title":"SVX Wallet API","version":"4.0.1"},"servers":[{"url":"https://zyfla-wallet-sandbox.meeco.cloud","description":"SVX Wallet deployment (relative)"}],"security":[],"paths":{"/admin/invitations/accept":{"post":{"summary":"Verify admin passkey registration","description":"Verifies the WebAuthn registration response produced by `navigator.credentials.create(...)` and persists\nthe admin passkey.\n\n`challenge_id` must match the value returned by `/admin/invitations/accept/options`.\n","operationId":"AdminAuthController_finishInvitationRegistration","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinishAdminPasskeyRegistrationRequestDto"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinishAdminPasskeyRegistrationResponseDto"}}},"description":"Registration verified"},"400":{"description":"Registration challenge is invalid or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPasskeyErrorResponseDto"}}}},"401":{"description":"Registration verification failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPasskeyErrorResponseDto"}}}},"404":{"description":"Invitation was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPasskeyErrorResponseDto"}}}},"409":{"description":"Invitation has already been used","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPasskeyErrorResponseDto"}}}}},"tags":["Admin Authentication"]}}},"components":{"schemas":{"FinishAdminPasskeyRegistrationRequestDto":{"type":"object","properties":{"secret_token":{"type":"string","description":"Invitation secret token returned by `/admin/invitations`."},"challenge_id":{"type":"string","description":"Challenge identifier returned by `/admin/invitations/accept/options`."},"response":{"type":"object","additionalProperties":true,"description":"Serialized WebAuthn registration credential from `navigator.credentials.create(...)`.\n\nExpected content typically includes:\n- `id` and `rawId`: Newly created credential identifier values.\n- `type`: Usually `public-key`.\n- `response.clientDataJSON`: Base64URL-encoded client data.\n- `response.attestationObject`: Base64URL-encoded attestation object.\n- `response.transports`: Optional list of authenticator transports.\n- `clientExtensionResults`: Optional extension output.\n\nSend the JSON-safe object produced by your WebAuthn client helper/library.\n"}},"required":["secret_token","challenge_id","response"]},"FinishAdminPasskeyRegistrationResponseDto":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"Identifier of the admin account."},"passkey_id":{"type":"string","format":"uuid","description":"Identifier of the created passkey credential."},"passkeys_count":{"type":"integer","description":"Total number of passkeys currently registered for the account."}},"required":["account_id","passkey_id","passkeys_count"]},"AdminPasskeyErrorResponseDto":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"extra_info":{"type":"object","additionalProperties":true}},"required":["error","message","extra_info"]}}}}
```
## Start admin passkey authentication
> Starts WebAuthn authentication and returns \`PublicKeyCredentialRequestOptionsJSON\`.\
> \
> Use the returned \`options\` with \`navigator.credentials.get(...)\`, then submit the resulting assertion to\
> \`/admin/session\` together with \`challenge\_id\`.
```json
{"openapi":"3.1.0","info":{"title":"SVX Wallet API","version":"4.0.1"},"servers":[{"url":"https://zyfla-wallet-sandbox.meeco.cloud","description":"SVX Wallet deployment (relative)"}],"security":[],"paths":{"/admin/session/options":{"post":{"summary":"Start admin passkey authentication","description":"Starts WebAuthn authentication and returns `PublicKeyCredentialRequestOptionsJSON`.\n\nUse the returned `options` with `navigator.credentials.get(...)`, then submit the resulting assertion to\n`/admin/session` together with `challenge_id`.\n","operationId":"AdminAuthController_startAuthentication","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartAdminPasskeyAuthenticationOptionsResponseDto"}}},"description":"Authentication options generated"}},"tags":["Admin Authentication"]}}},"components":{"schemas":{"StartAdminPasskeyAuthenticationOptionsResponseDto":{"type":"object","properties":{"challenge_id":{"type":"string","format":"uuid","description":"Challenge identifier required by `/admin/session`."},"options":{"type":"object","additionalProperties":true,"description":"WebAuthn `PublicKeyCredentialRequestOptionsJSON` payload to pass to `navigator.credentials.get({ publicKey: options })`.\n\nCommon fields:\n- `challenge`: Base64URL challenge generated by the server.\n- `rpId`: Relying Party ID to scope credential lookup.\n- `timeout`: Timeout in milliseconds.\n- `allowCredentials`: List of credential descriptors allowed for authentication.\n- `userVerification`: User verification requirement (`required`, `preferred`, or `discouraged`).\n- `extensions`: Optional WebAuthn extensions.\n"}},"required":["challenge_id","options"]}}}}
```
## Verify admin passkey authentication
> Verifies the WebAuthn assertion produced by \`navigator.credentials.get(...)\`.\
> \
> On success, returns an admin access token response and sets an HTTP-only refresh token cookie\
> (\`admin\_refresh\_token\`) valid for 7 days.
```json
{"openapi":"3.1.0","info":{"title":"SVX Wallet API","version":"4.0.1"},"servers":[{"url":"https://zyfla-wallet-sandbox.meeco.cloud","description":"SVX Wallet deployment (relative)"}],"security":[],"paths":{"/admin/session":{"post":{"summary":"Verify admin passkey authentication","description":"Verifies the WebAuthn assertion produced by `navigator.credentials.get(...)`.\n\nOn success, returns an admin access token response and sets an HTTP-only refresh token cookie\n(`admin_refresh_token`) valid for 7 days.\n","operationId":"AdminAuthController_finishAuthentication","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinishAdminPasskeyAuthenticationRequestDto"}}},"required":true},"responses":{"200":{"headers":{"Set-Cookie":{"schema":{"type":"string"},"description":"HTTP-only refresh token cookie (`admin_refresh_token`) scoped to `/admin/session/refresh`.\nThe cookie has a fixed 7-day expiry (non-sliding).\n"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinishAdminPasskeyAuthenticationResponseDto"}}},"description":"Authentication verified"},"400":{"description":"Authentication challenge is invalid or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPasskeyErrorResponseDto"}}}},"401":{"description":"Authentication verification failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPasskeyErrorResponseDto"}}}},"404":{"description":"Passkey was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPasskeyErrorResponseDto"}}}}},"tags":["Admin Authentication"]}}},"components":{"schemas":{"FinishAdminPasskeyAuthenticationRequestDto":{"type":"object","properties":{"challenge_id":{"type":"string","description":"Challenge identifier returned by `/admin/session/options`."},"response":{"type":"object","additionalProperties":true,"description":"Serialized WebAuthn assertion from `navigator.credentials.get(...)`.\n\nExpected content typically includes:\n- `id` and `rawId`: Credential identifier values.\n- `type`: Usually `public-key`.\n- `response.clientDataJSON`: Base64URL-encoded client data.\n- `response.authenticatorData`: Base64URL-encoded authenticator data.\n- `response.signature`: Base64URL-encoded assertion signature.\n- `response.userHandle`: Optional user handle when provided by the authenticator.\n\nSend the JSON-safe object produced by your WebAuthn client helper/library.\n"}},"required":["challenge_id","response"]},"FinishAdminPasskeyAuthenticationResponseDto":{"type":"object","properties":{"name":{"type":"string","description":"Authenticated admin display name."},"access_token":{"type":"string","description":"Signed JWT access token."},"token_type":{"type":"string","description":"OAuth token type."},"expires_in":{"type":"integer","description":"Access token lifetime in seconds."}},"required":["name","access_token","token_type","expires_in"]},"AdminPasskeyErrorResponseDto":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"extra_info":{"type":"object","additionalProperties":true}},"required":["error","message","extra_info"]}}}}
```
## Refresh admin access token
> Issues a new admin access token using the HTTP-only \`admin\_refresh\_token\` cookie.\
> \
> On success, the server rotates the refresh token value and returns it via \`Set-Cookie\` with the same\
> \`/admin/session/refresh\` path and fixed 7-day expiry (non-sliding).
```json
{"openapi":"3.1.0","info":{"title":"SVX Wallet API","version":"4.0.1"},"servers":[{"url":"https://zyfla-wallet-sandbox.meeco.cloud","description":"SVX Wallet deployment (relative)"}],"security":[],"paths":{"/admin/session/refresh":{"post":{"summary":"Refresh admin access token","description":"Issues a new admin access token using the HTTP-only `admin_refresh_token` cookie.\n\nOn success, the server rotates the refresh token value and returns it via `Set-Cookie` with the same\n`/admin/session/refresh` path and fixed 7-day expiry (non-sliding).\n","operationId":"AdminAuthController_refreshAuthentication","parameters":[],"responses":{"200":{"headers":{"Set-Cookie":{"schema":{"type":"string"},"description":"Rotated HTTP-only refresh token cookie (`admin_refresh_token`) scoped to `/admin/session/refresh`.\nThe cookie maintains the original fixed 7-day expiry (non-sliding).\n"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinishAdminPasskeyAuthenticationResponseDto"}}},"description":"Access token refreshed"},"401":{"description":"Refresh token cookie is missing, invalid, or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPasskeyErrorResponseDto"}}}}},"tags":["Admin Authentication"]}}},"components":{"schemas":{"FinishAdminPasskeyAuthenticationResponseDto":{"type":"object","properties":{"name":{"type":"string","description":"Authenticated admin display name."},"access_token":{"type":"string","description":"Signed JWT access token."},"token_type":{"type":"string","description":"OAuth token type."},"expires_in":{"type":"integer","description":"Access token lifetime in seconds."}},"required":["name","access_token","token_type","expires_in"]},"AdminPasskeyErrorResponseDto":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"extra_info":{"type":"object","additionalProperties":true}},"required":["error","message","extra_info"]}}}}
```