openapi: 3.1.0
info:
  title: Snapchat Login Kit API
  description: >-
    Snapchat Login Kit enables developers to let users sign up and log
    in to their apps using their Snapchat account credentials. Built on
    the OAuth 2.0 standard, it provides endpoints for authorization,
    token exchange, token refresh, and retrieving user profile information
    including display name and Bitmoji avatar. Login Kit is available
    for iOS, Android, and Web platforms.
  version: '1.0'
  contact:
    name: Snap for Developers
    url: https://developers.snap.com
  termsOfService: https://snap.com/en-US/terms
externalDocs:
  description: Snapchat Login Kit Documentation
  url: https://developers.snap.com/snap-kit/login-kit/overview
servers:
  - url: https://accounts.snapchat.com
    description: Snapchat Accounts Server (OAuth)
  - url: https://kit.snapchat.com/v1
    description: Snapchat Kit API Server (Profile)
tags:
  - name: OAuth
    description: >-
      OAuth 2.0 authorization and token management endpoints for
      authenticating users via their Snapchat account.
  - name: User Profile
    description: >-
      Endpoints for retrieving authenticated user profile information
      including display name and Bitmoji avatar.
paths:
  /accounts/oauth2/auth:
    get:
      operationId: authorize
      summary: Authorize a User via Snapchat
      description: >-
        Redirects the user to the Snapchat authorization page where
        they can grant permission to the application. This is the
        initial step in the OAuth 2.0 authorization code flow.
        After authorization, the user is redirected back to the
        specified redirect URI with an authorization code.
      tags:
        - OAuth
      parameters:
        - name: client_id
          in: query
          required: true
          description: >-
            The OAuth client ID assigned to the application.
          schema:
            type: string
        - name: redirect_uri
          in: query
          required: true
          description: >-
            The URI to redirect the user to after authorization.
            Must match one of the registered redirect URIs.
          schema:
            type: string
            format: uri
        - name: response_type
          in: query
          required: true
          description: >-
            The OAuth response type. Use 'code' for authorization
            code flow or 'token' for implicit flow.
          schema:
            type: string
            enum:
              - code
              - token
        - name: scope
          in: query
          required: true
          description: >-
            Space-separated list of requested scopes defining what
            user data the application wants access to.
          schema:
            type: string
            examples:
              - https://auth.snapchat.com/oauth2/api/user.display_name https://auth.snapchat.com/oauth2/api/user.bitmoji.avatar
        - name: state
          in: query
          required: false
          description: >-
            An opaque value used to maintain state between the
            request and callback for CSRF protection.
          schema:
            type: string
      responses:
        '302':
          description: >-
            Redirects to Snapchat login page for user authorization
        '400':
          description: Bad request - invalid parameters
  /login/oauth2/access_token:
    post:
      operationId: exchangeToken
      summary: Exchange Authorization Code for Tokens
      description: >-
        Exchanges an authorization code for an access token and
        refresh token. Access tokens expire after 3600 seconds
        (60 minutes). This endpoint is also used to refresh
        expired access tokens using a refresh token.
      tags:
        - OAuth
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - client_id
                - client_secret
                - grant_type
              properties:
                grant_type:
                  type: string
                  description: >-
                    The type of token exchange. Use 'authorization_code'
                    for initial exchange or 'refresh_token' for renewal.
                  enum:
                    - authorization_code
                    - refresh_token
                client_id:
                  type: string
                  description: >-
                    The OAuth client ID assigned to the application.
                client_secret:
                  type: string
                  description: >-
                    The OAuth client secret assigned to the application.
                code:
                  type: string
                  description: >-
                    The authorization code received from the authorization
                    endpoint. Required when grant_type is authorization_code.
                redirect_uri:
                  type: string
                  format: uri
                  description: >-
                    The redirect URI used in the authorization request.
                    Required when grant_type is authorization_code.
                refresh_token:
                  type: string
                  description: >-
                    The refresh token for obtaining a new access token.
                    Required when grant_type is refresh_token.
      responses:
        '200':
          description: Token exchange successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Bad request - invalid grant or parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '401':
          description: Unauthorized - invalid client credentials
  /me:
    get:
      operationId: getUserProfile
      summary: Get Authenticated User Profile
      description: >-
        Retrieves the profile information of the authenticated
        Snapchat user, including their external ID, display name,
        and Bitmoji avatar URL based on the scopes granted during
        authorization.
      tags:
        - User Profile
      security:
        - bearerAuth: []
      parameters:
        - name: query
          in: query
          required: false
          description: >-
            A JSON-encoded query string specifying which fields
            to retrieve from the user profile.
          schema:
            type: string
      responses:
        '200':
          description: User profile retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '401':
          description: Unauthorized - invalid or expired access token
        '403':
          description: Forbidden - insufficient scopes
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer access token obtained via the OAuth 2.0 authorization
        code flow. Tokens expire after 3600 seconds.
  schemas:
    TokenResponse:
      type: object
      description: >-
        The response from a successful token exchange or refresh request.
      properties:
        access_token:
          type: string
          description: >-
            The access token for authenticating API requests.
        token_type:
          type: string
          description: >-
            The type of token, always 'Bearer'.
          enum:
            - Bearer
        expires_in:
          type: integer
          description: >-
            The number of seconds until the access token expires.
            Typically 3600 (60 minutes).
          example: 3600
        refresh_token:
          type: string
          description: >-
            The refresh token for obtaining new access tokens
            after expiration.
        scope:
          type: string
          description: >-
            The scopes granted by the user during authorization.
    OAuthError:
      type: object
      description: >-
        Error response from the OAuth token endpoint.
      properties:
        error:
          type: string
          description: >-
            The error code.
          enum:
            - invalid_request
            - invalid_client
            - invalid_grant
            - unauthorized_client
            - unsupported_grant_type
        error_description:
          type: string
          description: >-
            A human-readable description of the error.
    UserProfile:
      type: object
      description: >-
        The authenticated user's Snapchat profile information.
        Fields available depend on the scopes granted during
        authorization.
      properties:
        data:
          type: object
          properties:
            me:
              type: object
              properties:
                externalId:
                  type: string
                  description: >-
                    The unique external identifier for the user
                    on the Snapchat platform.
                displayName:
                  type: string
                  description: >-
                    The user's Snapchat display name. Requires the
                    user.display_name scope.
                bitmoji:
                  type: object
                  description: >-
                    The user's Bitmoji avatar information. Requires
                    the user.bitmoji.avatar scope.
                  properties:
                    avatar:
                      type: string
                      format: uri
                      description: >-
                        URL to the user's Bitmoji avatar image.
                    id:
                      type: string
                      description: >-
                        The unique identifier of the user's Bitmoji.