# Enroll TOTP

`POST /gate/mfa/totp/enroll` · Identity & Access · Sign-in & Sessions

Initiates TOTP (time-based one-time password) MFA enrollment for the authenticated end-user, returning a provisioning QR code and the raw TOTP secret for scanning with an authenticator app. Ten single-use recovery codes are generated at this step and must be saved before enrollment is confirmed. Enrollment is not active until confirmed via the confirm endpoint.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `projectSlug` | path | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `label` | string | no | A name for the authenticator, shown in the methods list. Default `TOTP`. |

```json
{
  "label": "string"
}
```

## Responses

- **200**: Success

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes | The authenticator app that was enrolled. |
| `data.factor` | object | yes | The new, unconfirmed authenticator. Confirm it with a code from the app. |
| `data.factor.id` | string | yes | The authenticator's id (`eumf_...`). |
| `data.factor.secret` | string | yes | The TOTP seed, base32. It is shown only in this response and is never readable again: show it (or `uri` as a QR code) to the end user once and do not store it. The authenticator is unusable until confirmed. |
| `data.factor.uri` | string | yes | An `otpauth://totp/...` provisioning URI with the seed, issuer and settings (SHA1, 6 digits, 30-second period). Render it as a QR code for the authenticator app to scan. |
| `meta` | object | yes | Request metadata: cost, timing and the request and trace ids. |


## Errors

| HTTP | Code | When |
|---|---|---|
| 401 | `K9O_SESSION_EXPIRED` | Your session has expired or been revoked. Sign in again to continue. |
| 404 | `K9O_END_USER_NOT_FOUND` | No account was found for the provided identity. |

## Code samples

### cURL

```bash
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/gate/mfa/totp/enroll' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "label": "string"
}'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/gate/mfa/totp/enroll', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "label": "string"
}),
});
const { data, meta } = await res.json();
```

### @k9o/core

```typescript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.gate.mfa.totp.enroll({
  label: 'string'
})
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/identity-access/enroll-totp
