---
title: "Add To Allowlist"
method: POST
path: "/api/v1/admin/signup-gate/allowlist"
tags: ["admin-signup-gate"]
---

# Add To Allowlist

`POST /api/v1/admin/signup-gate/allowlist`

## Request

- Base URL: `https://memory.kagura-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://memory.kagura-ai.com/api/v1/admin/signup-gate/allowlist`
- Auth: none declared

Add a GitHub or Google user to the manual allowlist (#655).

Provider is set explicitly via ``payload.provider`` (defaulting to
``"github"`` for pre-#655 callers). The required field per provider:

* ``provider="github"`` → ``github_username`` (resolved to numeric ID
  via the GitHub API).
* ``provider="google"`` → ``email`` (resolved to OIDC ``sub`` via the
  local ``users`` table; the user must have OAuth'd at least once).

## Request body

- AllowlistAddRequest: Allowlist add payload (provider-aware since #655). Three accepted shapes: * GitHub legacy (pre-#655): ``{github_username}`` — preserved verbatim so existing admin tooling keeps working without a flag day. * GitHub canonical: ``{provider: "github", github_username}`` — same semantics, but with the discriminator explicit. * Google: ``{provider: "google", email}`` — resolves the user's OIDC ``sub`` by looking up an existing ``users`` row with ``auth_provider='google'`` and matching email (v1 bootstrap UX — pre-OAuth invitation lands in Phase 2). Pydantic validates ``github_username`` shape when present (1–39 chars, alphanumeric + hyphens, no leading/trailing hyphen) so malformed payloads don't spend a GitHub API request (rate-limited to 60/hr unauthenticated). The ``email`` field uses the same regex pattern that the rest of the codebase uses for email-string validation (see ``models/schemas.py:830``); switching to ``pydantic.EmailStr`` would require pulling in ``email-validator`` as a new dependency, which is not warranted for a single field.
  - `provider` 'github' | 'google'
  - `github_username` string, nullable
  - `email` string, nullable

## Response `201`

Successful Response

- AllowlistEntryResponse: Allowlist entry read-model. #655 added ``provider`` / ``subject_id`` / ``subject_label`` as the canonical fields. The legacy ``github_user_id`` / ``github_username`` fields are retained on the response for backward compatibility with pre-#655 admin tooling — for ``provider='google'`` rows these carry the sentinel values written by ``add_to_allowlist_entry`` (``"google:<sub>"`` / email), which existing GitHub-only consumers can ignore via the new ``provider`` field.
  - `id` unknown, required
  - `provider` unknown, required
  - `subject_id` unknown, required
  - `subject_label` unknown, required
  - `github_user_id` unknown, required
  - `github_username` unknown, required
  - `source` unknown, required
  - `state` unknown, required
  - `added_by_user_id` unknown, required
  - `created_at` unknown, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud.md) · [All operations](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/revisions/09f17f5ada29?raw)