Make an API key

POST

/api/auth/api-keys

curl --request POST \
  --url http://localhost:3000/api/auth/api-keys \
  --header 'Content-Type: application/json' \
  --cookie merran.session_token=<merran.session_token> \
  --data '{ "name": "Home Assistant", "permissions": { "recipes": "read", "list": "write" }, "expiresInDays": 90 }'

• Your Merran

For the household in use, or another of yours named in household. It acts as you there, with only the permissions given, and stops working if you leave. The key is shown only in this response. Making a key needs a sign-in: a key can’t make another.

Authorizations

• session

Request Body^required

Media typeapplication/json

object

name

required

string

>= 1 characters <= 100 characters

permissions

required

object

household

string

Allowed values: read

recipes

string

Allowed values: read write

plan

string

Allowed values: read write

list

string

Allowed values: read write

pantry

string

Allowed values: read write

imports

string

Allowed values: read write

assistant

string

Allowed values: read write

Example

{
  "recipes": "read",
  "list": "write"
}

household

Which of your households it’s for: the one in use when left out.

string

expiresInDays

Any of:

number

number

Allowed values: 30

number

number

Allowed values: 90

number

number

Allowed values: 365

null

null

Example

{
  "name": "Home Assistant",
  "permissions": {
    "recipes": "read",
    "list": "write"
  },
  "expiresInDays": 90
}

Responses

201

Made. Copy the key now.

Media typeapplication/json

object

id

required

string

name

required

string

start

required

string

household

required

object

id

required

string

name

required

string

permissions

required

object

household

string

Allowed values: read

recipes

string

Allowed values: read write

plan

string

Allowed values: read write

list

string

Allowed values: read write

pantry

string

Allowed values: read write

imports

string

Allowed values: read write

assistant

string

Allowed values: read write

expiresAt

required

string | null format: date-time

lastUsedAt

required

string | null format: date-time

createdAt

required

string format: date-time

key

required

string

Example

{
  "id": "0199e8b0-5a10-7a01-8b00-000000000009",
  "name": "Home Assistant",
  "start": "mrn_3fK9aQ",
  "household": {
    "id": "0199e8b0-5a10-7a01-8b00-000000000003",
    "name": "The Riveras"
  },
  "permissions": {
    "recipes": "read",
    "list": "write"
  },
  "expiresAt": "2027-01-13T18:30:00.000Z",
  "lastUsedAt": null,
  "createdAt": "2026-10-01T17:30:00.000Z",
  "key": "mrn_3fK9aQ…"
}

401

Not signed in.

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

fields

object

key

additional properties

string

Example

{
  "error": {
    "code": "not_found",
    "message": "There's nothing here.",
    "fields": {
      "name": "Give it a name."
    }
  }
}

403

Not allowed.

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

fields

object

key

additional properties

string

Example

{
  "error": {
    "code": "not_found",
    "message": "There's nothing here.",
    "fields": {
      "name": "Give it a name."
    }
  }
}