SuperTokens Authentication

naftiko: "1.0.0-alpha1"

info:
  label: "SuperTokens Authentication"
  description: >-
    Unified authentication workflow combining all SuperTokens Core authentication
    capabilities. Covers session management, email/password auth, passwordless OTP
    and magic links, third-party OAuth (Google, GitHub, Apple), email verification,
    password reset, user metadata, multi-tenancy, user management, and role-based
    access control.
  tags:
    - SuperTokens
    - Authentication
    - Session Management
    - Identity
    - OAuth
    - Passwordless
    - Multi-Tenancy
    - Open Source
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SUPERTOKENS_CORE_HOST: SUPERTOKENS_CORE_HOST
      SUPERTOKENS_API_KEY: SUPERTOKENS_API_KEY

capability:
  consumes:
    - import: supertokens-cdi
      location: ./shared/core-driver-interface.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: supertokens-auth-api
      description: "Unified REST API for SuperTokens authentication and identity management."
      resources:
        - path: /v1/sessions
          name: sessions
          description: "Session lifecycle management"
          operations:
            - method: POST
              name: create-session
              description: "Create a new authentication session"
              call: "supertokens-cdi.create-session"
              with:
                user_id: "rest.user_id"
                jwt_data: "rest.jwt_data"
                db_data: "rest.db_data"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: get-session
              description: "Verify an access token and get session data"
              call: "supertokens-cdi.get-session"
              with:
                accessToken: "rest.accessToken"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: refresh-session
              description: "Refresh a session using a refresh token"
              call: "supertokens-cdi.refresh-session"
              with:
                refresh_token: "rest.refresh_token"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: remove-sessions
              description: "Revoke sessions by handle or user ID"
              call: "supertokens-cdi.remove-sessions"
              with:
                session_handles: "rest.session_handles"
                user_id: "rest.user_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/auth/signup
          name: email-password-signup
          description: "Email/password sign-up"
          operations:
            - method: POST
              name: signup
              description: "Create new user with email and password"
              call: "supertokens-cdi.signup"
              with:
                email: "rest.email"
                password: "rest.password"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/auth/signin
          name: email-password-signin
          description: "Email/password sign-in"
          operations:
            - method: POST
              name: signin
              description: "Sign in with email and password"
              call: "supertokens-cdi.signin"
              with:
                email: "rest.email"
                password: "rest.password"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/auth/password/reset
          name: password-reset
          description: "Password reset flow"
          operations:
            - method: POST
              name: create-reset-token
              description: "Generate password reset token"
              call: "supertokens-cdi.create-reset-password-token"
              with:
                user_id: "rest.user_id"
                email: "rest.email"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PUT
              name: reset-password
              description: "Reset password using token"
              call: "supertokens-cdi.reset-password"
              with:
                token: "rest.token"
                new_password: "rest.new_password"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/auth/passwordless/code
          name: passwordless-code
          description: "Passwordless authentication"
          operations:
            - method: POST
              name: create-code
              description: "Create passwordless OTP or magic link"
              call: "supertokens-cdi.create-passwordless-code"
              with:
                email: "rest.email"
                phone_number: "rest.phone_number"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: consume-code
              description: "Consume code to authenticate user"
              call: "supertokens-cdi.consume-passwordless-code"
              with:
                pre_auth_session_id: "rest.pre_auth_session_id"
                otp_code: "rest.otp_code"
                device_id: "rest.device_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/auth/thirdparty
          name: third-party-auth
          description: "Third-party OAuth authentication"
          operations:
            - method: POST
              name: thirdparty-signinup
              description: "Sign in or up via OAuth provider"
              call: "supertokens-cdi.third-party-signinup"
              with:
                provider_id: "rest.provider_id"
                provider_user_id: "rest.provider_user_id"
                email_object: "rest.email_object"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/auth/email/verify
          name: email-verification
          description: "Email verification"
          operations:
            - method: POST
              name: create-verification-token
              description: "Generate email verification token"
              call: "supertokens-cdi.create-email-verification-token"
              with:
                user_id: "rest.user_id"
                email: "rest.email"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PUT
              name: verify-email
              description: "Verify email with token"
              call: "supertokens-cdi.verify-email"
              with:
                token: "rest.token"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: is-email-verified
              description: "Check email verification status"
              call: "supertokens-cdi.is-email-verified"
              with:
                userId: "rest.userId"
                email: "rest.email"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/users
          name: users
          description: "User management"
          operations:
            - method: GET
              name: list-users
              description: "List all users"
              call: "supertokens-cdi.list-users"
              with:
                limit: "rest.limit"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: delete-user
              description: "Delete a user permanently"
              call: "supertokens-cdi.delete-user"
              with:
                userId: "rest.userId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/users/{userId}/metadata
          name: user-metadata
          description: "User metadata storage"
          operations:
            - method: GET
              name: get-user-metadata
              description: "Get user metadata"
              call: "supertokens-cdi.get-user-metadata"
              with:
                userId: "rest.userId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PUT
              name: update-user-metadata
              description: "Update user metadata"
              call: "supertokens-cdi.update-user-metadata"
              with:
                user_id: "rest.user_id"
                metadata: "rest.metadata"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/users/{userId}/roles
          name: user-roles
          description: "User role management"
          operations:
            - method: GET
              name: get-user-roles
              description: "Get roles assigned to a user"
              call: "supertokens-cdi.get-user-roles"
              with:
                userId: "rest.userId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PUT
              name: assign-role
              description: "Assign a role to a user"
              call: "supertokens-cdi.assign-role-to-user"
              with:
                user_id: "rest.user_id"
                role: "rest.role"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: remove-role
              description: "Remove a role from a user"
              call: "supertokens-cdi.remove-user-role"
              with:
                userId: "rest.userId"
                role: "rest.role"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/tenants
          name: tenants
          description: "Multi-tenant configuration"
          operations:
            - method: GET
              name: list-tenants
              description: "List all tenants"
              call: "supertokens-cdi.list-tenants"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-or-update-tenant
              description: "Create or update a tenant"
              call: "supertokens-cdi.create-or-update-tenant"
              with:
                tenant_id: "rest.tenant_id"
                email_password_enabled: "rest.email_password_enabled"
                passwordless_enabled: "rest.passwordless_enabled"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: supertokens-auth-mcp
      transport: http
      description: "MCP server for AI-assisted SuperTokens authentication management."
      tools:
        - name: create-session
          description: "Create a new authenticated session for a user"
          hints:
            readOnly: false
            idempotent: false
          call: "supertokens-cdi.create-session"
          with:
            user_id: "tools.user_id"
            jwt_data: "tools.jwt_data"
            db_data: "tools.db_data"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-session
          description: "Verify and retrieve session data from an access token"
          hints:
            readOnly: true
            idempotent: true
          call: "supertokens-cdi.get-session"
          with:
            accessToken: "tools.accessToken"
          outputParameters:
            - type: object
              mapping: "$."
        - name: refresh-session
          description: "Refresh an authentication session using a refresh token"
          hints:
            readOnly: false
            idempotent: false
          call: "supertokens-cdi.refresh-session"
          with:
            refresh_token: "tools.refresh_token"
          outputParameters:
            - type: object
              mapping: "$."
        - name: remove-sessions
          description: "Revoke sessions for a user or specific session handles"
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "supertokens-cdi.remove-sessions"
          with:
            session_handles: "tools.session_handles"
            user_id: "tools.user_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: signup
          description: "Create a new user account with email and password"
          hints:
            readOnly: false
            idempotent: false
          call: "supertokens-cdi.signup"
          with:
            email: "tools.email"
            password: "tools.password"
          outputParameters:
            - type: object
              mapping: "$."
        - name: signin
          description: "Authenticate a user with email and password"
          hints:
            readOnly: false
            idempotent: false
          call: "supertokens-cdi.signin"
          with:
            email: "tools.email"
            password: "tools.password"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-passwordless-code
          description: "Generate a passwordless OTP or magic link for sign in"
          hints:
            readOnly: false
            idempotent: false
          call: "supertokens-cdi.create-passwordless-code"
          with:
            email: "tools.email"
            phone_number: "tools.phone_number"
          outputParameters:
            - type: object
              mapping: "$."
        - name: consume-passwordless-code
          description: "Authenticate user by consuming a passwordless OTP or magic link"
          hints:
            readOnly: false
            idempotent: false
          call: "supertokens-cdi.consume-passwordless-code"
          with:
            pre_auth_session_id: "tools.pre_auth_session_id"
            otp_code: "tools.otp_code"
            device_id: "tools.device_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: thirdparty-signinup
          description: "Sign in or create user via OAuth provider (Google, GitHub, Apple, etc.)"
          hints:
            readOnly: false
            idempotent: false
          call: "supertokens-cdi.third-party-signinup"
          with:
            provider_id: "tools.provider_id"
            provider_user_id: "tools.provider_user_id"
            email_object: "tools.email_object"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-email-verification-token
          description: "Generate an email verification token to send to the user"
          hints:
            readOnly: false
            idempotent: false
          call: "supertokens-cdi.create-email-verification-token"
          with:
            user_id: "tools.user_id"
            email: "tools.email"
          outputParameters:
            - type: object
              mapping: "$."
        - name: verify-email
          description: "Verify a user's email address using their verification token"
          hints:
            readOnly: false
            idempotent: true
          call: "supertokens-cdi.verify-email"
          with:
            token: "tools.token"
          outputParameters:
            - type: object
              mapping: "$."
        - name: is-email-verified
          description: "Check whether a user's email has been verified"
          hints:
            readOnly: true
            idempotent: true
          call: "supertokens-cdi.is-email-verified"
          with:
            userId: "tools.userId"
            email: "tools.email"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-users
          description: "List all users with pagination"
          hints:
            readOnly: true
            idempotent: true
          call: "supertokens-cdi.list-users"
          with:
            limit: "tools.limit"
          outputParameters:
            - type: object
              mapping: "$."
        - name: delete-user
          description: "Permanently delete a user and all their data"
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "supertokens-cdi.delete-user"
          with:
            userId: "tools.userId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-user-metadata
          description: "Retrieve custom metadata stored for a user"
          hints:
            readOnly: true
            idempotent: true
          call: "supertokens-cdi.get-user-metadata"
          with:
            userId: "tools.userId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: update-user-metadata
          description: "Update custom metadata for a user (shallow merge)"
          hints:
            readOnly: false
            idempotent: false
          call: "supertokens-cdi.update-user-metadata"
          with:
            user_id: "tools.user_id"
            metadata: "tools.metadata"
          outputParameters:
            - type: object
              mapping: "$."
        - name: assign-role-to-user
          description: "Assign a role to a user for RBAC"
          hints:
            readOnly: false
            idempotent: true
          call: "supertokens-cdi.assign-role-to-user"
          with:
            user_id: "tools.user_id"
            role: "tools.role"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-user-roles
          description: "Get all roles assigned to a user"
          hints:
            readOnly: true
            idempotent: true
          call: "supertokens-cdi.get-user-roles"
          with:
            userId: "tools.userId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-tenants
          description: "List all configured tenants in a multi-tenant deployment"
          hints:
            readOnly: true
            idempotent: true
          call: "supertokens-cdi.list-tenants"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-or-update-tenant
          description: "Create or configure a tenant in a multi-tenant setup"
          hints:
            readOnly: false
            idempotent: true
          call: "supertokens-cdi.create-or-update-tenant"
          with:
            tenant_id: "tools.tenant_id"
            email_password_enabled: "tools.email_password_enabled"
            passwordless_enabled: "tools.passwordless_enabled"
          outputParameters:
            - type: object
              mapping: "$."