Superwall

Superwall Grants V2 API

Query manual entitlement grants by device or user.

GitHub OpenAPI

Operations 1

GET /v2/grants List Grants by Device #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/superwall/openapi/superwall-grants-v2-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/superwall/json-schema/superwall-audit-log-entry-with-actor-schema.json
📊
JSONSchema
https://artifacts.apis.io/superwall/json-schema/superwall-custom-store-event-schema.json
📊
JSONSchema
https://artifacts.apis.io/superwall/json-schema/superwall-rule-conditions-schema.json
📊
JSONSchema
https://artifacts.apis.io/superwall/json-schema/superwall-rule-conditions-1-schema.json
📊
JSONSchema
https://artifacts.apis.io/superwall/json-schema/superwall-doctor-report-schema.json
📊
JSONSchema
https://artifacts.apis.io/superwall/json-schema/superwall-audit-log-list-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/superwall:superwall-grants-v2-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API 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.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

superwall-grants-v2-api-openapi.yml Raw ↑ 
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