Auth API

mero.auth (AuthApi) is the node’s authentication surface — token issuance and the management of root keys and client keys. It’s a Sendable struct over the shared HttpClient; methods are async throws unless noted.

Tip

For the common case — logging in and staying logged in — you don’t call this directly. mero.authenticate() uses generateTokens, and the transport calls refreshToken for you. Reach for mero.auth when you need key management or provider details.

Tokens & session

Method	Endpoint
getHealth() -> HealthResponse	GET /auth/health
getIdentity() -> IdentityResponse	GET /admin/identity
getProviders() -> ProvidersResponse	GET /auth/providers
generateTokens(_ request: TokenRequest) -> TokenResponse	POST /auth/token
refreshToken(_ request: RefreshTokenRequest) -> TokenResponse	POST /auth/refresh
generateMockTokens(_ request: MockTokenRequest) -> TokenResponse	POST /auth/mock-token (dev)
validateToken(_ token: String) -> TokenValidation	HEAD /auth/validate — async, not throws
revokeTokens(_ request: RevokeTokenRequest) -> RevokeTokenResponse	POST /admin/revoke
logout(_ request: LogoutRequest) -> LogoutResponse	POST /auth/logout (core rc.83)

await mero.logout() calls logout with the stored refresh token, then clears the session locally. The server half is best-effort: an unreachable node, an older node without the route, or a 401 for a token the node already refuses never keeps the caller logged in.

Caution

Log in again after upgrading the node to core rc.83. Tokens gained a required key_id claim, so every access and refresh token minted by an older node fails verification. A stored session from before the upgrade surfaces as a 401; clear it (await mero.clearToken()) and call authenticate again. A token’s sub is now an opaque user id, not a key id or username.

Root keys

Method	Endpoint
listRootKeys() -> [RootKey]	GET /admin/keys
createRootKey(_ request: CreateKeyRequest) -> CreateKeyResponse	POST /admin/keys
deleteRootKey(_ keyId: String) -> DeleteKeyResponse	DELETE /admin/keys/{keyId}
getKeyPermissions(_ keyId: String) -> PermissionResponse	GET /admin/keys/{keyId}/permissions
updateKeyPermissions(_ keyId: String, changes: UpdateKeyPermissionsRequest) -> PermissionResponse	PUT /admin/keys/{keyId}/permissions

updateKeyPermissions sends an { add, remove } delta of permission strings, not a replacement.

Client keys

Method	Endpoint
listClientKeys() -> [ClientKey]	GET /admin/keys/clients
generateClientKey(_ request: GenerateClientKeyRequest) -> TokenResponse	POST /admin/client-key
deleteClientKey(keyId: String, clientId: String) -> DeleteClientResponse	DELETE /admin/keys/{keyId}/clients/{clientId}

GenerateClientKeyRequest takes applicationId (binds the key to one app) and ttlSecs since rc.83. A client key is narrower than the session that mints it:

• It expires. ttlSecs defaults to 30 days and there is no non-expiring key. Its access token lives 15 minutes and its refresh token 7 days.
• keys:* permissions are never grantable to it, and admin only when it binds no context (no contextId, no contextIdentity). Anything else is a 400.
• It acts only on the contexts and groups it is bound to. Elsewhere it gets a 403, including on JSON-RPC and SSE subscribe.

Key types

struct TokenResponse: Codable, Sendable {
  let data: Payload            // { accessToken, refreshToken, error? }
  let error: String?
}

struct IdentityResponse: Codable, Sendable {
  let service: String
  let version: String
  let authenticationMode: String   // wire: authentication_mode
  let providers: [String]
}

struct RootKey: Codable, Sendable {
  let keyId, publicKey, authMethod: String
  let createdAt: Int
  let revokedAt: Int?
  let permissions: [String]
}

struct ClientKey: Codable, Sendable {
  let clientId, rootKeyId, name: String
  let permissions: [String]
  let createdAt: Int
  let revokedAt: Int?
  let isValid: Bool
}

struct TokenRequest: Codable, Sendable {          // built for you by mero.authenticate()
  let authMethod, publicKey, clientName: String
  let permissions: [String]?
  let timestamp: Int
  let providerData: [String: JSONValue]
}

Note

Auth request/response fields are snake_case on the wire (via CodingKeys) — they mirror the node exactly. The admin API, by contrast, is camelCase.

See AuthTypes.swift for the complete set.