# Institflow Account

Sign-up, email verification, sign-in, password reset, sessions, profile, email change, export and delete for the Institflow account — the control-plane identity a student, guardian or institute owner uses across every institute they belong to (id.institflow.com). Cloud/control-plane only: answers 404 on a self-hosted install.

Generated from `apps/api/openapi.json`. HTML version: https://docs.institflow.com/en/reference/accounts

20 operations.

## POST /api/v1/accounts/forgot-password

Request a password-reset email (always 200, whether or not the account exists).

- Operation id: `AccountsController_forgotPassword_v1`
- Permission: —
- Auth: public (no credential)
- `Idempotency-Key`: not required

### Request body

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |

```json
{
  "email": "ada.lovelace@example.com"
}
```

### Responses

**200** — A reset email was sent, if the account exists.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `ok` | enum: true | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X POST "https://your-institute.example/api/v1/accounts/forgot-password" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "email": "ada.lovelace@example.com"
  }'
```

## POST /api/v1/accounts/logout

Revoke the current account session.

- Operation id: `AccountsController_logout_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: not required

### Responses

**200** — The session was revoked.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `ok` | enum: true | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X POST "https://your-institute.example/api/v1/accounts/logout" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"
```

## POST /api/v1/accounts/logout-all

Revoke every session (every device) for the current account.

- Operation id: `AccountsController_logoutAll_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: not required

### Responses

**200** — Every session was revoked.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `ok` | enum: true | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X POST "https://your-institute.example/api/v1/accounts/logout-all" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"
```

## DELETE /api/v1/accounts/me

Delete the account (typed confirmation: the current password). Institute links and sessions cascade.

- Operation id: `AccountsController_deleteMe_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: not required

### Request body

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `currentPassword` | string | yes | ≥1 chars |

```json
{
  "currentPassword": "string"
}
```

### Responses

**200** — The account was deleted.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `ok` | enum: true | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X DELETE "https://your-institute.example/api/v1/accounts/me" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "currentPassword": "string"
  }'
```

## GET /api/v1/accounts/me

The current account.

- Operation id: `AccountsController_me_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: not required

### Responses

**200** — The account profile.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |
| `email` | string (email) | yes |  |
| `username` | string | yes |  |
| `phone` | string \| null | yes |  |
| `phoneVerified` | boolean | yes |  |
| `locale` | enum: "ar" \| "en" \| "he" | yes |  |
| `status` | enum: "active" \| "disabled" | yes |  |
| `emailVerified` | boolean | yes |  |
| `signupIntent` | enum: "institute_owner" \| "student" \| "guardian" \| null \| null | yes |  |
| `createdAt` | string (date-time) | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X GET "https://your-institute.example/api/v1/accounts/me" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"
```

## PATCH /api/v1/accounts/me

Update username, locale or phone. Changing the phone resets its verification.

- Operation id: `AccountsController_updateMe_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: not required

### Request body

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `username` | string | no |  |
| `locale` | enum: "ar" \| "en" \| "he" | no |  |
| `phone` | string \| null | no |  |

```json
{
  "username": "string",
  "locale": "ar",
  "phone": "+15551234567"
}
```

### Responses

**200** — The updated account.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |
| `email` | string (email) | yes |  |
| `username` | string | yes |  |
| `phone` | string \| null | yes |  |
| `phoneVerified` | boolean | yes |  |
| `locale` | enum: "ar" \| "en" \| "he" | yes |  |
| `status` | enum: "active" \| "disabled" | yes |  |
| `emailVerified` | boolean | yes |  |
| `signupIntent` | enum: "institute_owner" \| "student" \| "guardian" \| null \| null | yes |  |
| `createdAt` | string (date-time) | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X PATCH "https://your-institute.example/api/v1/accounts/me" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "username": "string",
    "locale": "ar",
    "phone": "+15551234567"
  }'
```

## POST /api/v1/accounts/me/change-email

Request an email change — sends a confirmation link to the NEW address.

- Operation id: `AccountsController_changeEmail_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: not required

### Request body

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `newEmail` | string (email) | yes |  |
| `currentPassword` | string | yes | ≥1 chars |

```json
{
  "newEmail": "ada.lovelace@example.com",
  "currentPassword": "string"
}
```

### Responses

**200** — A confirmation link was sent.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `ok` | enum: true | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X POST "https://your-institute.example/api/v1/accounts/me/change-email" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "newEmail": "ada.lovelace@example.com",
    "currentPassword": "string"
  }'
```

## POST /api/v1/accounts/me/change-password

Change your own password. Revokes every OTHER session (this one stays signed in).

- Operation id: `AccountsController_changePassword_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: not required

### Request body

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `currentPassword` | string | yes | ≥1 chars |
| `newPassword` | string | yes | ≥10 chars |

```json
{
  "currentPassword": "string",
  "newPassword": "string"
}
```

### Responses

**200** — The password was changed.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `ok` | enum: true | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X POST "https://your-institute.example/api/v1/accounts/me/change-password" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "currentPassword": "string",
    "newPassword": "string"
  }'
```

## POST /api/v1/accounts/me/confirm-email

Confirm a pending email change from the link sent to the new address.

- Operation id: `AccountsController_confirmEmail_v1`
- Permission: —
- Auth: public (no credential)
- `Idempotency-Key`: not required

### Request body

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `token` | string | yes | ≥1 chars |

```json
{
  "token": "string"
}
```

### Responses

**200** — The email address was changed.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `ok` | enum: true | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X POST "https://your-institute.example/api/v1/accounts/me/confirm-email" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "token": "string"
  }'
```

## GET /api/v1/accounts/me/export

A JSON export of the account fields and the institutes it belongs to.

- Operation id: `AccountsController_exportData_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: not required

### Responses

**200** — The export.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `account` | object | yes |  |
| `termsVersion` | string \| null | yes |  |
| `termsAcceptedAt` | string (date-time) \| null | yes |  |
| `institutes` | array<object> | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X GET "https://your-institute.example/api/v1/accounts/me/export" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"
```

## GET /api/v1/accounts/me/institutes

The account's invited/active institute links (K-52) — name and install address included, for My institutes' "Open" action.

- Operation id: `AccountsController_institutes_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: not required

### Responses

**200** — The institute links.

```json
[
  {
    "id": "37386ae0-3738-7738-8386-37386ae03738",
    "tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
    "kind": "student",
    "status": "invited",
    "invitedAt": "2026-03-02T09:00:00.000Z",
    "activatedAt": "2026-03-02T09:00:00.000Z",
    "instituteName": "string",
    "address": "string"
  }
]
```

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X GET "https://your-institute.example/api/v1/accounts/me/institutes" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"
```

## POST /api/v1/accounts/me/institutes/{id}/decline

Decline an institute's invitation (phase 19). The link becomes `declined` and the institute sees the answer; the institute may invite you again.

- Operation id: `AccountsController_declineInstitute_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: not required

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Responses

**200** — The invitation was declined.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `ok` | enum: true | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X POST "https://your-institute.example/api/v1/accounts/me/institutes/37386ae0-3738-7738-8386-37386ae03738/decline" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"
```

## GET /api/v1/accounts/me/sessions

Every active session for the current account.

- Operation id: `AccountsController_sessions_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: not required

### Responses

**200** — The active sessions.

```json
[
  {
    "id": "37386ae0-3738-7738-8386-37386ae03738",
    "userAgent": "string",
    "ip": "string",
    "lastUsedAt": "2026-03-02T09:00:00.000Z",
    "createdAt": "2026-03-02T09:00:00.000Z"
  }
]
```

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X GET "https://your-institute.example/api/v1/accounts/me/sessions" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"
```

## DELETE /api/v1/accounts/me/sessions/{id}

Revoke one of your own sessions.

- Operation id: `AccountsController_revokeSession_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: not required

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Responses

**200** — The session was revoked.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `ok` | enum: true | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X DELETE "https://your-institute.example/api/v1/accounts/me/sessions/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"
```

## POST /api/v1/accounts/refresh

Rotate the refresh token (from the cookie) and issue a new access token.

- Operation id: `AccountsController_refresh_v1`
- Permission: —
- Auth: public (no credential)
- `Idempotency-Key`: not required

### Responses

**200** — A new access token; the cookie is rotated too.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `accessToken` | string | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X POST "https://your-institute.example/api/v1/accounts/refresh" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"
```

## POST /api/v1/accounts/resend-verification

Resend the verification code (always 202, whether or not the email exists or is already verified).

- Operation id: `AccountsController_resendVerification_v1`
- Permission: —
- Auth: public (no credential)
- `Idempotency-Key`: not required

### Request body

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |

```json
{
  "email": "ada.lovelace@example.com"
}
```

### Responses

**202** — A code was sent, if applicable.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `ok` | enum: true | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X POST "https://your-institute.example/api/v1/accounts/resend-verification" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "email": "ada.lovelace@example.com"
  }'
```

## POST /api/v1/accounts/reset-password

Reset a password using a token from the forgot-password email. Clears any lockout (K-47).

- Operation id: `AccountsController_resetPassword_v1`
- Permission: —
- Auth: public (no credential)
- `Idempotency-Key`: not required

### Request body

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `token` | string | yes | ≥1 chars |
| `password` | string | yes | ≥10 chars |

```json
{
  "token": "string",
  "password": "string"
}
```

### Responses

**200** — The password was reset.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `ok` | enum: true | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X POST "https://your-institute.example/api/v1/accounts/reset-password" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "token": "string",
    "password": "string"
  }'
```

## POST /api/v1/accounts/sign-in

Sign in with an email or username + password. Refuses ACCOUNT_EMAIL_UNVERIFIED until the address is verified.

- Operation id: `AccountsController_signIn_v1`
- Permission: —
- Auth: public (no credential)
- `Idempotency-Key`: not required

### Request body

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `identifier` | string | yes | ≥1 chars |
| `password` | string | yes | ≥1 chars |

```json
{
  "identifier": "string",
  "password": "string"
}
```

### Responses

**200** — An access token (refresh token set as a cookie) and the account.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `accessToken` | string | yes |  |
| `account` | object | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X POST "https://your-institute.example/api/v1/accounts/sign-in" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "identifier": "string",
    "password": "string"
  }'
```

## POST /api/v1/accounts/sign-up

Create an Institflow account and mail a 6-digit verification code.

- Operation id: `AccountsController_signUp_v1`
- Permission: —
- Auth: public (no credential)
- `Idempotency-Key`: not required

### Request body

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `username` | string | yes |  |
| `password` | string | yes | ≥10 chars |
| `phone` | string | no |  |
| `locale` | enum: "ar" \| "en" \| "he" | yes |  |
| `termsVersion` | enum: "2026-09-23" | yes |  |
| `signupIntent` | enum: "institute_owner" \| "student" \| "guardian" | yes |  |

```json
{
  "email": "ada.lovelace@example.com",
  "username": "string",
  "password": "string",
  "phone": "+15551234567",
  "locale": "ar",
  "termsVersion": "2026-09-23",
  "signupIntent": "institute_owner"
}
```

### Responses

**201** — The newly created account (email not yet verified).

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |
| `email` | string (email) | yes |  |
| `username` | string | yes |  |
| `phone` | string \| null | yes |  |
| `phoneVerified` | boolean | yes |  |
| `locale` | enum: "ar" \| "en" \| "he" | yes |  |
| `status` | enum: "active" \| "disabled" | yes |  |
| `emailVerified` | boolean | yes |  |
| `signupIntent` | enum: "institute_owner" \| "student" \| "guardian" \| null \| null | yes |  |
| `createdAt` | string (date-time) | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X POST "https://your-institute.example/api/v1/accounts/sign-up" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "email": "ada.lovelace@example.com",
    "username": "string",
    "password": "string",
    "phone": "+15551234567",
    "locale": "ar",
    "termsVersion": "2026-09-23",
    "signupIntent": "institute_owner"
  }'
```

## POST /api/v1/accounts/verify-email

Verify an email address with the 6-digit code sent at sign-up (5 attempts per code). Returns signupIntent for post-verify routing (docs/specs/phase17-unified-login.md §4).

- Operation id: `AccountsController_verifyEmail_v1`
- Permission: —
- Auth: public (no credential)
- `Idempotency-Key`: not required

### Request body

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `code` | string | yes |  |

```json
{
  "email": "ada.lovelace@example.com",
  "code": "string"
}
```

### Responses

**200** — The email address was verified.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `ok` | enum: true | yes |  |
| `signupIntent` | enum: "institute_owner" \| "student" \| "guardian" \| null \| null | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
curl -X POST "https://your-institute.example/api/v1/accounts/verify-email" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "email": "ada.lovelace@example.com",
    "code": "string"
  }'
```