Auth API

mero.auth (AuthApi) wraps the node’s /auth and /admin identity/key endpoints. Most apps don’t call it directly — mero.authenticate() and mero.logout() drive token generation and revocation, and the transport handles refresh reactively. Reach for mero.auth for providers and key management. Every method is a suspend fun.

Methods

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
validateToken(token: String): ValidationResult	HEAD /auth/validate
revokeTokens(request: RevokeTokenRequest): RevokeTokenResponse	POST /admin/revoke
generateMockTokens(request: MockTokenRequest): TokenResponse	POST /auth/mock-token
listRootKeys(): List<RootKey>	GET /admin/keys
createRootKey(request: CreateKeyRequest): CreateKeyResponse	POST /admin/keys
deleteRootKey(keyId: String): DeleteKeyResponse	DELETE /admin/keys/{keyId}
listClientKeys(): List<ClientKey>	GET /admin/keys/clients
generateClientKey(request: GenerateClientKeyRequest): TokenResponse	POST /admin/client-key
deleteClientKey(keyId, clientId): DeleteClientResponse	DELETE /admin/keys/{keyId}/clients/{clientId}
getKeyPermissions(keyId: String): PermissionResponse	GET /admin/keys/{keyId}/permissions
updateKeyPermissions(keyId, changes: UpdateKeyPermissionsRequest): PermissionResponse	PUT /admin/keys/{keyId}/permissions

Note

validateToken sends Authorization: Bearer <token> and never throws on a 401 — inspect the returned ValidationResult.valid / status.

Caution

updateKeyPermissions applies a delta, not a replacement: core removes remove first, then adds add. A permissions field is ignored, so sending the full desired set silently does nothing.

mero.auth.updateKeyPermissions(keyId, UpdateKeyPermissionsRequest(add = listOf("admin")))

generateMockTokens mints a token pair with no provider handshake — dev nodes and CI only; production nodes reject it.

Types

Wire is snake_case; Kotlin properties are camelCase via @SerialName.

data class HealthResponse(val status: String, val storage: Boolean, val uptimeSeconds: Long)

data class IdentityResponse(
    val service: String, val version: String,
    val authenticationMode: String, val providers: List<String> = emptyList(),
)

data class Provider(
    val name: String, val type: String, val description: String = "",
    val configured: Boolean = false, val config: JsonObject = JsonObject(emptyMap()),
)
data class ProvidersResponse(val providers: List<Provider> = emptyList(), val count: Int = 0)

data class TokenRequest(
    val authMethod: String, val publicKey: String, val clientName: String,
    val permissions: List<String>? = null, val timestamp: Long, val providerData: JsonObject,
)
data class TokenPayload(val accessToken: String, val refreshToken: String, val error: String? = null)
data class TokenResponse(val data: TokenPayload, val error: String? = null)
data class RefreshTokenRequest(val accessToken: String, val refreshToken: String)

data class RevokeTokenRequest(val clientId: String)       // core revokes by client_id
data class RevokeTokenResponse(val success: Boolean, val message: String)

data class RootKey(
    val keyId: String, val publicKey: String, val authMethod: String,
    val createdAt: Long = 0, val revokedAt: Long? = null, val permissions: List<String> = emptyList(),
)
data class ClientKey(
    val clientId: String, val rootKeyId: String, val name: String = "",
    val permissions: List<String> = emptyList(),
    val createdAt: Long = 0, val revokedAt: Long? = null, val isValid: Boolean = true,
)

data class ValidationResult(val valid: Boolean, val status: Int, val headers: Map<String, String>)