---
title: "Set Project Auth Mode"
method: PUT
path: "/v2/projects/{id}/auth/mode"
tags: ["Project Auth V2"]
---

# Set Project Auth Mode

`PUT /v2/projects/{id}/auth/mode`

## Request

- Base URL: `https://api.superwall.com`
- URL: `https://api.superwall.com/v2/projects/{id}/auth/mode`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `accounts_superwall_token`
  - HTTP bearer

Sets the project's Superwall Auth mode and returns the whole configuration. `required` needs at least one enabled method, or it is a 409. Turning Superwall Auth on is a 403 until it is available to the project; `off` always works. Requires projects:write scope.

## Path parameters

- `id` string, required

## Request body

- object
  - `mode` 'off' | 'optional' | 'required', required: `off`: sign-in is refused. `optional`: tokens are verified when sent; client-asserted user ids still work. `required`: a request that names an identified (non-anonymous) user id must carry a valid access token for that user; anonymous ids still work.

## Response `200`

Success

- object
  - `object` 'project_auth', required
  - `project_id` string, required
  - `mode` 'off' | 'optional' | 'required', required: `off`: sign-in is refused. `optional`: tokens are verified when sent; client-asserted user ids still work. `required`: a request that names an identified (non-anonymous) user id must carry a valid access token for that user; anonymous ids still work.
  - `issuer` string, nullable, required: Superwall's own issuer for this project: the `iss` (and `aud`) of the access tokens Superwall signs. `null` when this environment has no issuer configured.
  - `jwks_url` string, nullable, required: Where Superwall publishes the keys that sign this project's access tokens, so a backend can verify them offline. `null` when `issuer` is.
  - `methods` union[], required: Every configured sign-in method, enabled or not, oldest first.
    - union
      - object: An identity provider whose ID tokens the project accepts.
        - `object` 'project_auth_method', required
        - `id` string, required
        - `project_id` string, required
        - `type` 'oidc' | 'apple' | 'google' | 'firebase', required: `apple` (Sign in with Apple), `google` (Google Sign-In), `firebase` (Firebase Authentication) or `oidc` (any OpenID Connect issuer, e.g. Supabase or Auth0).
        - `issuer` string, required: The `iss` an ID token must carry, exactly as the provider issues it.
        - `audiences` string[], required: Accepted `aud` values. A token must name at least one.
        - `app_user_id_claim` string, required: The ID token claim whose value becomes the app user id.
        - `enabled` boolean, required: Disabled methods are kept but no longer accept tokens.
        - `created_at` string, required: ISO 8601 creation timestamp
        - `updated_at` string, required: ISO 8601 last-update timestamp
      - object: Superwall's built-in email sign-in: users get a 6-digit code by email and, with a link domain, a link that opens the app. A project has at most one.
        - `object` 'project_auth_method', required
        - `id` string, required
        - `project_id` string, required
        - `type` 'email', required
        - `link_domain` string, nullable, required: The web paywall domain whose links open the app from the sign-in email. `null` sends the code alone, as does a domain that has since been deleted.
        - `link_host` string, nullable, required: The host the sign-in link opens, which the app must claim (iOS universal links, Android App Links). `null` when there is no `link_domain`, or this environment has no app-link domain.
        - `enabled` boolean, required: Disabled methods are kept but no longer send codes or accept them.
        - `created_at` string, required: ISO 8601 creation timestamp
        - `updated_at` string, required: ISO 8601 last-update timestamp

## Other responses

- `400`: The request did not match the expected schema | The request was invalid or malformed
- `401`: No API key was provided in the request | The API key does not have a valid format | The API key is invalid or has been revoked | An error occurred while validating the API key | The session cookie is invalid or expired
- `403`: The API key does not have permission to perform this action
- `404`: The requested resource was not found
- `409`: The resource already exists or conflicts with an existing resource
- `429`: Too many requests have been made in a short period
- `500`: An unexpected error occurred on the server

## Changes

- **2026-11-02** `6d77be7f87b5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/superwall/apis/superwall-api-v2/changes/v2/projects/:id/auth/mode/put.md)

---

[API](https://skmtc.dev/superwall/apis/superwall-api-v2.md) - [All operations](https://skmtc.dev/superwall/apis/superwall-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/superwall/apis/superwall-api-v2/revisions/523b4734dfab?raw)