> For the complete documentation index, see [llms.txt](https://docs.mimic.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mimic.fi/developers/api/users.md).

# Users

User authentication and profile management

## Request an authentication nonce

> Returns a nonce for the given address. The caller must sign this nonce and submit it to \`POST /users/authenticate\` to obtain a JWT.<br>

```json
{"openapi":"3.0.3","info":{"title":"Mimic Protocol API","version":"1.0.1"},"tags":[{"name":"Users","description":"User authentication and profile management"}],"servers":[{"url":"https://api-protocol.mimic.fi"}],"paths":{"/users/nonce":{"post":{"summary":"Request an authentication nonce","description":"Returns a nonce for the given address. The caller must sign this nonce and submit it to `POST /users/authenticate` to obtain a JWT.\n","operationId":"getUserNonce","tags":["Users"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserNonceRequest"}}}},"responses":{"200":{"description":"Nonce generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserNonceResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"UserNonceRequest":{"type":"object","required":["address"],"properties":{"address":{"$ref":"#/components/schemas/Address"}}},"Address":{"type":"string","description":"A valid EVM (0x-prefixed hex) address."},"UserNonceResponse":{"type":"object","required":["address","nonce"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"nonce":{"$ref":"#/components/schemas/HexString"}}},"HexString":{"type":"string","description":"An arbitrary 0x-prefixed hex string."},"Error":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Authenticate with a signed nonce

> Verifies the EIP-191 signature of the nonce returned by \`POST /users/nonce\` and returns a JWT token.<br>

```json
{"openapi":"3.0.3","info":{"title":"Mimic Protocol API","version":"1.0.1"},"tags":[{"name":"Users","description":"User authentication and profile management"}],"servers":[{"url":"https://api-protocol.mimic.fi"}],"paths":{"/users/authenticate":{"post":{"summary":"Authenticate with a signed nonce","description":"Verifies the EIP-191 signature of the nonce returned by `POST /users/nonce` and returns a JWT token.\n","operationId":"authenticateUser","tags":["Users"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserAuthenticationRequest"}}}},"responses":{"200":{"description":"Authentication successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserAuthenticationResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}},"components":{"schemas":{"UserAuthenticationRequest":{"type":"object","required":["address","signature"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"signature":{"allOf":[{"$ref":"#/components/schemas/Signature"}],"description":"Signature of the nonce obtained from `POST /users/nonce`"}}},"Address":{"type":"string","description":"A valid EVM (0x-prefixed hex) address."},"Signature":{"type":"string","description":"A 65-byte hex-encoded ECDSA signature (130 hex chars + 0x prefix)."},"UserAuthenticationResponse":{"type":"object","required":["address","token"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"token":{"type":"string","description":"JWT to pass in `x-auth-token` on subsequent requests"},"email":{"type":"string","format":"email"}}},"Error":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## GET /users/api-key

> Get the authenticated user's API key

```json
{"openapi":"3.0.3","info":{"title":"Mimic Protocol API","version":"1.0.1"},"tags":[{"name":"Users","description":"User authentication and profile management"}],"servers":[{"url":"https://api-protocol.mimic.fi"}],"security":[{"jwtAuth":[]}],"components":{"securitySchemes":{"jwtAuth":{"type":"apiKey","in":"header","name":"x-auth-token","description":"JWT token obtained from `POST /users/authenticate`"}},"schemas":{"UserApiKeyResponse":{"type":"object","required":["address","apiKey"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"apiKey":{"type":"string"}}},"Address":{"type":"string","description":"A valid EVM (0x-prefixed hex) address."},"Error":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/users/api-key":{"get":{"summary":"Get the authenticated user's API key","operationId":"getUserApiKey","tags":["Users"],"responses":{"200":{"description":"API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserApiKeyResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## GET /users/tokens

> Get token balances for the authenticated user

```json
{"openapi":"3.0.3","info":{"title":"Mimic Protocol API","version":"1.0.1"},"tags":[{"name":"Users","description":"User authentication and profile management"}],"servers":[{"url":"https://api-protocol.mimic.fi"}],"security":[{"jwtAuth":[]}],"components":{"securitySchemes":{"jwtAuth":{"type":"apiKey","in":"header","name":"x-auth-token","description":"JWT token obtained from `POST /users/authenticate`"}},"schemas":{"UserToken":{"type":"object","required":["chainId","address","symbol","decimals","balance","allowance","price","logo"],"properties":{"chainId":{"$ref":"#/components/schemas/ChainId"},"address":{"$ref":"#/components/schemas/Address"},"symbol":{"type":"string"},"decimals":{"type":"integer","minimum":0},"balance":{"$ref":"#/components/schemas/BigInteger"},"allowance":{"$ref":"#/components/schemas/BigInteger"},"price":{"type":"number"},"logo":{"type":"string","format":"uri"}}},"ChainId":{"type":"integer","description":"A supported chain ID."},"Address":{"type":"string","description":"A valid EVM (0x-prefixed hex) address."},"BigInteger":{"type":"string","description":"A non-negative integer represented as a decimal string."},"Error":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/users/tokens":{"get":{"summary":"Get token balances for the authenticated user","operationId":"getUserTokens","tags":["Users"],"responses":{"200":{"description":"List of token balances across chains","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UserToken"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Get user profile data

> Only the authenticated user may read their own profile.

```json
{"openapi":"3.0.3","info":{"title":"Mimic Protocol API","version":"1.0.1"},"tags":[{"name":"Users","description":"User authentication and profile management"}],"servers":[{"url":"https://api-protocol.mimic.fi"}],"security":[{"jwtAuth":[]}],"components":{"securitySchemes":{"jwtAuth":{"type":"apiKey","in":"header","name":"x-auth-token","description":"JWT token obtained from `POST /users/authenticate`"}},"parameters":{"AddressParam":{"name":"address","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Address"}}},"schemas":{"Address":{"type":"string","description":"A valid EVM (0x-prefixed hex) address."},"UserData":{"type":"object","required":["userAddress","name","intendedUse"],"properties":{"userAddress":{"$ref":"#/components/schemas/EvmAddress"},"name":{"type":"string"},"intendedUse":{"type":"string","maxLength":255},"email":{"type":"string","format":"email","nullable":true}}},"EvmAddress":{"type":"string","description":"A valid EVM address (0x-prefixed, 20 bytes)."},"Error":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Forbidden — caller is not allowed to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/users/{address}/data":{"get":{"summary":"Get user profile data","description":"Only the authenticated user may read their own profile.","operationId":"getUserData","tags":["Users"],"parameters":[{"$ref":"#/components/parameters/AddressParam"}],"responses":{"200":{"description":"User profile data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserData"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
```

## Update user profile data

> Only the authenticated user may update their own profile.

```json
{"openapi":"3.0.3","info":{"title":"Mimic Protocol API","version":"1.0.1"},"tags":[{"name":"Users","description":"User authentication and profile management"}],"servers":[{"url":"https://api-protocol.mimic.fi"}],"security":[{"jwtAuth":[]}],"components":{"securitySchemes":{"jwtAuth":{"type":"apiKey","in":"header","name":"x-auth-token","description":"JWT token obtained from `POST /users/authenticate`"}},"parameters":{"AddressParam":{"name":"address","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Address"}}},"schemas":{"Address":{"type":"string","description":"A valid EVM (0x-prefixed hex) address."},"UserDataUpdateRequest":{"type":"object","properties":{"name":{"type":"string"},"intendedUse":{"type":"string","maxLength":255}}},"UserData":{"type":"object","required":["userAddress","name","intendedUse"],"properties":{"userAddress":{"$ref":"#/components/schemas/EvmAddress"},"name":{"type":"string"},"intendedUse":{"type":"string","maxLength":255},"email":{"type":"string","format":"email","nullable":true}}},"EvmAddress":{"type":"string","description":"A valid EVM address (0x-prefixed, 20 bytes)."},"Error":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Forbidden — caller is not allowed to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/users/{address}/data":{"post":{"summary":"Update user profile data","description":"Only the authenticated user may update their own profile.","operationId":"updateUserData","tags":["Users"],"parameters":[{"$ref":"#/components/parameters/AddressParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserDataUpdateRequest"}}}},"responses":{"200":{"description":"Updated user profile data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserData"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
```