Superwall Grants V2 API
Query manual entitlement grants by device or user.
Query manual entitlement grants by device or user.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/superwall:superwall-grants-v2-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Superwall API V2 Grants V2 API
version: 2.0.0
description: Superwall V2 API - Scope-based authentication with organization API keys
servers:
- url: https://api.superwall.com
description: Production
- url: https://api.superwall.dev
description: Staging
- url: /
description: Local
security: []
tags:
- name: Grants V2
description: Query manual entitlement grants by device or user.
paths:
/v2/grants:
get:
tags:
- Grants V2
operationId: grantsv2.listGrantsByDevice
parameters:
- name: limit
in: query
schema:
anyOf:
- type: string
required: false
- name: starting_after
in: query
schema:
anyOf:
- type: string
description: Cursor for forward pagination - returns items after this grant ID
required: false
- name: ending_before
in: query
schema:
anyOf:
- type: string
description: Cursor for backward pagination - returns items before this grant ID
required: false
- name: project_id
in: query
schema:
type: string
required: true
- name: device_id
in: query
schema:
anyOf:
- type: string
description: Filter by device ID
required: false
- name: user_id
in: query
schema:
anyOf:
- type: string
description: Filter by user ID
required: false
- name: include_expired
in: query
schema:
anyOf:
- type: string
enum:
- 'true'
- 'false'
required: false
- name: include_revoked
in: query
schema:
anyOf:
- type: string
enum:
- 'true'
- 'false'
required: false
security:
- bearer: []
- cookie: []
- oauth: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
object:
type: string
enum:
- list
description: Object type, always `list`
url:
type: string
enum:
- /v2/grants
description: API endpoint URL for this list
has_more:
type: boolean
description: Whether there are more results available beyond this page
data:
type: array
items:
type: object
properties:
id:
type: string
object:
type: string
enum:
- entitlement_grant
description: Object type, always `entitlement_grant`
entitlement:
type: string
entitlement_identifier:
type: string
description: Identifier string of the entitlement being granted
user_id:
anyOf:
- type: string
- type: 'null'
description: User ID the grant applies to, or null
device_id:
type: string
description: Device ID the grant applies to
expires_at:
anyOf:
- type: string
- type: 'null'
description: ISO 8601 timestamp of when the grant expires, or null for permanent grants
reason:
anyOf:
- type: string
- type: 'null'
description: Reason for the grant, or null
granted_by:
type: string
description: Identifier of who granted this entitlement
granted_at:
type: string
description: ISO 8601 timestamp of when the grant was created
status:
anyOf:
- type: string
enum:
- active
description: Grant is currently active
- type: string
enum:
- expired
description: Grant has expired
- type: string
enum:
- revoked
description: Grant has been revoked
description: Current status of the grant
required:
- id
- object
- entitlement
- entitlement_identifier
- user_id
- device_id
- expires_at
- reason
- granted_by
- granted_at
- status
additionalProperties: false
description: List of results
required:
- object
- url
- has_more
- data
additionalProperties: false
'400':
description: The request did not match the expected schema | The request was invalid or malformed
content:
application/json:
schema:
anyOf:
- type: object
properties:
_tag:
type: string
enum:
- HttpApiDecodeError
issues:
type: array
items:
type: object
properties:
_tag:
type: string
enum:
- Type
- Missing
- Unexpected
- Forbidden
- Pointer
- Refinement
- Transformation
- Composite
path:
type: array
items:
anyOf:
- type: string
- type: number
- type: object
properties:
_tag:
type: string
enum:
- symbol
key:
type: string
required:
- _tag
- key
additionalProperties: false
message:
type: string
required:
- _tag
- path
- message
additionalProperties: false
message:
type: string
required:
- _tag
- issues
- message
additionalProperties: false
- type: object
properties:
_tag:
type: string
enum:
- '@superwall/api-schema/v2/errors/BadRequest'
type:
anyOf:
- type: string
enum:
- api_error
- authentication_error
- invalid_request_error
- rate_limit_error
- permission_error
code:
type: string
enum:
- resource_missing
- resource_already_exists
- resource_archived
- parameter_invalid
- parameter_missing
- parameter_unknown
- invalid_reference
- unsupported_operation
- idempotency_key_in_use
- rate_limit_exceeded
- invalid_api_key
- invalid_api_key_format
- missing_api_key
- authentication_failed
- invalid_session
- organization_required
- insufficient_permissions
- internal_error
- upstream_service_error
- side_effect_failed
message:
type: string
param:
anyOf:
- type: string
doc_url:
anyOf:
- type: string
required:
- _tag
- code
- message
additionalProperties: false
'401':
description: 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
content:
application/json:
schema:
anyOf:
- type: object
properties:
_tag:
type: string
enum:
- '@superwall/api-schema/v2/errors/MissingApiKey'
type:
anyOf:
- type: string
enum:
- api_error
- authentication_error
- invalid_request_error
- rate_limit_error
- permission_error
code:
anyOf:
- type: string
enum:
- resource_missing
- resource_already_exists
- resource_archived
- parameter_invalid
- parameter_missing
- parameter_unknown
- invalid_reference
- unsupported_operation
- idempotency_key_in_use
- rate_limit_exceeded
- invalid_api_key
- invalid_api_key_format
- missing_api_key
- authentication_failed
- invalid_session
- organization_required
- insufficient_permissions
- internal_error
- upstream_service_error
- side_effect_failed
message:
anyOf:
- type: string
doc_url:
anyOf:
- type: string
required:
- _tag
additionalProperties: false
- type: object
properties:
_tag:
type: string
enum:
- '@superwall/api-schema/v2/errors/InvalidApiKeyFormat'
type:
anyOf:
- type: string
enum:
- api_error
- authentication_error
- invalid_request_error
- rate_limit_error
- permission_error
code:
anyOf:
- type: string
enum:
- resource_missing
- resource_already_exists
- resource_archived
- parameter_invalid
- parameter_missing
- parameter_unknown
- invalid_reference
- unsupported_operation
- idempotency_key_in_use
- rate_limit_exceeded
- invalid_api_key
- invalid_api_key_format
- missing_api_key
- authentication_failed
- invalid_session
- organization_required
- insufficient_permissions
- internal_error
- upstream_service_error
- side_effect_failed
message:
anyOf:
- type: string
doc_url:
anyOf:
- type: string
required:
- _tag
additionalProperties: false
- type: object
properties:
_tag:
type: string
enum:
- '@superwall/api-schema/v2/errors/InvalidApiKey'
type:
anyOf:
- type: string
enum:
- api_error
- authentication_error
- invalid_request_error
- rate_limit_error
- permission_error
code:
anyOf:
- type: string
enum:
- resource_missing
- resource_already_exists
- resource_archived
- parameter_invalid
- parameter_missing
- parameter_unknown
- invalid_reference
- unsupported_operation
- idempotency_key_in_use
- rate_limit_exceeded
- invalid_api_key
- invalid_api_key_format
- missing_api_key
- authentication_failed
- invalid_session
- organization_required
- insufficient_permissions
- internal_error
- upstream_service_error
- side_effect_failed
message:
anyOf:
- type: string
doc_url:
anyOf:
- type: string
required:
- _tag
additionalProperties: false
- type: object
properties:
_tag:
type: string
enum:
- '@superwall/api-schema/v2/errors/AuthenticationFailed'
type:
anyOf:
- type: string
enum:
- api_error
- authentication_error
- invalid_request_error
- rate_limit_error
- permission_error
code:
anyOf:
- type: string
enum:
- resource_missing
- resource_already_exists
- resource_archived
- parameter_invalid
- parameter_missing
- parameter_unknown
- invalid_reference
- unsupported_operation
- idempotency_key_in_use
- rate_limit_exceeded
- invalid_api_key
- invalid_api_key_format
- missing_api_key
- authentication_failed
- invalid_session
- organization_required
- insufficient_permissions
- internal_error
- upstream_service_error
- side_effect_failed
message:
anyOf:
- type: string
doc_url:
anyOf:
- type: string
required:
- _tag
additionalProperties: false
- type: object
properties:
_tag:
type: string
enum:
- '@superwall/api-schema/v2/errors/InvalidSession'
type:
anyOf:
- type: string
enum:
- api_error
- authentication_error
- invalid_request_error
- rate_limit_error
- permission_error
code:
anyOf:
- type: string
enum:
- resource_missing
- resource_already_exists
- resource_archived
- parameter_invalid
- parameter_missing
- parameter_unknown
- invalid_reference
- unsupported_operation
- idempotency_key_in_use
- rate_limit_exceeded
- invalid_api_key
- invalid_api_key_format
- missing_api_key
- authentication_failed
- invalid_session
- organization_required
- insufficient_permissions
- internal_error
- upstream_service_error
- side_effect_failed
message:
anyOf:
- type: string
required:
- _tag
additionalProperties: false
'403':
description: The API key does not have permission to perform this action
content:
application/json:
schema:
type: object
properties:
_tag:
type: string
enum:
- '@superwall/api-schema/v2/errors/PermissionError'
type:
anyOf:
- type: string
enum:
- api_error
- authentication_error
- invalid_request_error
- rate_limit_error
- permission_error
code:
anyOf:
- type: string
enum:
- resource_missing
- resource_already_exists
- resource_archived
- parameter_invalid
- parameter_missing
- parameter_unknown
- invalid_reference
- unsupported_operation
- idempotency_key_in_use
- rate_limit_exceeded
- invalid_api_key
- invalid_api_key_format
- missing_api_key
- authentication_failed
- invalid_session
- organization_required
- insufficient_permissions
- internal_error
- upstream_service_error
- side_effect_failed
message:
type: string
required_scope:
anyOf:
- type: string
doc_url:
anyOf:
- type: string
required:
- _tag
- message
additionalProperties: false
'404':
description: The requested resource was not found
content:
application/json:
schema:
type: object
properties:
_tag:
type: string
enum:
- '@superwall/api-schema/v2/errors/ResourceNotFound'
type:
anyOf:
- type: string
enum:
- api_error
- authentication_error
- invalid_request_error
- rate_limit_error
- permission_error
code:
anyOf:
- type: string
enum:
- resource_missing
- resource_already_exists
- resource_archived
- parameter_invalid
- parameter_missing
- parameter_unknown
- invalid_reference
- unsupported_operation
- idempotency_key_in_use
- rate_limit_exceeded
- invalid_api_key
- invalid_api_key_format
- missing_api_key
- authentication_failed
- invalid_session
- organization_required
- insufficient_permissions
- internal_error
- upstream_service_error
- side_effect_failed
message:
anyOf:
- type: string
param:
anyOf:
- type: string
doc_url:
anyOf:
- type: string
resource_type:
anyOf:
- type: string
resource_id:
anyOf:
- type: string
required:
- _tag
additionalProperties: false
'429':
description: Too many requests have been made in a short period
content:
application/json:
schema:
type: object
properties:
_tag:
type: string
enum:
- '@superwall/api-schema/v2/errors/RateLimit'
type:
anyOf:
- type: string
enum:
- api_error
- authentication_error
- invalid_request_error
- rate_limit_error
- permission_error
code:
anyOf:
- type: string
enum:
- resource_missing
- resource_already_exists
- resource_archived
- parameter_invalid
- parameter_missing
- parameter_unknown
- invalid_reference
- unsupported_operation
- idempotency_key_in_use
- rate_limit_exceeded
- invalid_api_key
- invalid_api_key_format
- missing_api_key
- authentication_failed
- invalid_session
- organization_required
- insufficient_permissions
- internal_error
- upstream_service_error
- side_effect_failed
message:
anyOf:
- type: string
retry_after:
anyOf:
- type: number
required:
- _tag
additionalProperties: false
'500':
description: An unexpected error occurred on the server
content:
application/json:
schema:
type: object
properties:
_tag:
type: string
enum:
- '@superwall/api-schema/v2/errors/InternalError'
type:
anyOf:
- type: string
enum:
- api_error
- authentication_error
- invalid_request_error
- rate_limit_error
- permission_error
code:
anyOf:
- type: string
enum:
- resource_missing
- resource_already_exists
- resource_archived
- parameter_invalid
- parameter_missing
- parameter_unknown
- invalid_reference
- unsupported_operation
- idempotency_key_in_use
- rate_limit_exceeded
- invalid_api_key
- invalid_api_key_format
- missing_api_key
- authentication_failed
- invalid_session
- organization_required
- insufficient_permissions
- internal_error
- upstream_service_error
- side_effect_failed
message:
anyOf:
- type: string
cause:
anyOf:
- {}
required:
- _tag
additionalProperties: false
description: Returns a list of manual grants for the specified device/user. Requires entitlements:read scope.
summary: List Grants by Device
components:
securitySchemes:
bearer:
type: http
scheme: Bearer
cookie:
type: apiKey
name: accounts_superwall_token
in: cookie
oauth:
type: http
scheme: Bearer