naftiko: 1.0.0-alpha2
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-06'
binds:
- namespace: env
  keys:
    SUPERTOKENS_CORE_HOST: SUPERTOKENS_CORE_HOST
    SUPERTOKENS_API_KEY: SUPERTOKENS_API_KEY
capability:
  consumes:
  - type: http
    namespace: supertokens-cdi
    baseUri: http://{{SUPERTOKENS_CORE_HOST}}:3567
    description: SuperTokens Core REST API
    authentication:
      type: apikey
      key: api-key
      value: '{{SUPERTOKENS_API_KEY}}'
      placement: header
    resources:
    - name: health
      path: /hello
      description: Service health check
      operations:
      - name: get-health
        method: GET
        description: Check if SuperTokens Core is running
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: sessions
      path: /recipe/session
      description: Session lifecycle management
      operations:
      - name: create-session
        method: POST
        description: Create a new authentication session
        body:
          type: json
          data:
            userId: '{{tools.user_id}}'
            userDataInJWT: '{{tools.jwt_data}}'
            userDataInDatabase: '{{tools.db_data}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-session
        method: GET
        description: Verify and get session from access token
        inputParameters:
        - name: accessToken
          in: query
          type: string
          required: true
          description: Access token to verify
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: refresh-session
        method: POST
        description: Refresh a session using refresh token
        body:
          type: json
          data:
            refreshToken: '{{tools.refresh_token}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: remove-sessions
        method: POST
        description: Revoke sessions by handle or user ID
        body:
          type: json
          data:
            sessionHandles: '{{tools.session_handles}}'
            userId: '{{tools.user_id}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: email-password
      path: /recipe
      description: Email/password authentication
      operations:
      - name: signup
        method: POST
        description: Create new user with email and password
        body:
          type: json
          data:
            email: '{{tools.email}}'
            password: '{{tools.password}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: signin
        method: POST
        description: Authenticate user with email and password
        body:
          type: json
          data:
            email: '{{tools.email}}'
            password: '{{tools.password}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-reset-password-token
        method: POST
        description: Generate password reset token for user
        body:
          type: json
          data:
            userId: '{{tools.user_id}}'
            email: '{{tools.email}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: reset-password
        method: POST
        description: Reset user password using reset token
        body:
          type: json
          data:
            method: token
            token: '{{tools.token}}'
            newPassword: '{{tools.new_password}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: passwordless
      path: /recipe/signinup
      description: Passwordless OTP and magic link auth
      operations:
      - name: create-passwordless-code
        method: POST
        description: Create passwordless OTP or magic link
        body:
          type: json
          data:
            email: '{{tools.email}}'
            phoneNumber: '{{tools.phone_number}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: consume-passwordless-code
        method: POST
        description: Consume passwordless code to authenticate
        body:
          type: json
          data:
            preAuthSessionId: '{{tools.pre_auth_session_id}}'
            userInputCode: '{{tools.otp_code}}'
            deviceId: '{{tools.device_id}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: third-party-signinup
        method: POST
        description: Sign in or up via OAuth provider
        body:
          type: json
          data:
            thirdPartyId: '{{tools.provider_id}}'
            thirdPartyUserId: '{{tools.provider_user_id}}'
            email: '{{tools.email_object}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: email-verification
      path: /recipe/user/email
      description: Email verification management
      operations:
      - name: create-email-verification-token
        method: POST
        description: Generate email verification token
        body:
          type: json
          data:
            userId: '{{tools.user_id}}'
            email: '{{tools.email}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: verify-email
        method: POST
        description: Verify email using verification token
        body:
          type: json
          data:
            method: token
            token: '{{tools.token}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: is-email-verified
        method: GET
        description: Check if user email is verified
        inputParameters:
        - name: userId
          in: query
          type: string
          required: true
          description: User ID
        - name: email
          in: query
          type: string
          required: true
          description: Email address
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: user-metadata
      path: /recipe/user/metadata
      description: User metadata storage
      operations:
      - name: get-user-metadata
        method: GET
        description: Get custom metadata for a user
        inputParameters:
        - name: userId
          in: query
          type: string
          required: true
          description: User ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: update-user-metadata
        method: PUT
        description: Update user metadata (shallow merge)
        body:
          type: json
          data:
            userId: '{{tools.user_id}}'
            metadataUpdate: '{{tools.metadata}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: delete-user-metadata
        method: DELETE
        description: Delete all metadata for a user
        inputParameters:
        - name: userId
          in: query
          type: string
          required: true
          description: User ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: multi-tenancy
      path: /recipe/multitenancy
      description: Multi-tenant configuration
      operations:
      - name: create-or-update-tenant
        method: POST
        description: Create or update tenant configuration
        body:
          type: json
          data:
            tenantId: '{{tools.tenant_id}}'
            emailPasswordEnabled: '{{tools.email_password_enabled}}'
            passwordlessEnabled: '{{tools.passwordless_enabled}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: list-tenants
        method: GET
        description: List all configured tenants
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: users
      path: /users
      description: User management
      operations:
      - name: list-users
        method: GET
        description: List all users with pagination
        inputParameters:
        - name: limit
          in: query
          type: integer
          required: false
          description: Max users to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: delete-user
        method: DELETE
        description: Permanently delete a user
        inputParameters:
        - name: userId
          in: query
          type: string
          required: true
          description: User ID to delete
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: user-roles
      path: /recipe/user/roles
      description: Role-based access control
      operations:
      - name: assign-role-to-user
        method: PUT
        description: Assign a role to a user
        body:
          type: json
          data:
            userId: '{{tools.user_id}}'
            role: '{{tools.role}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-user-roles
        method: GET
        description: Get all roles for a user
        inputParameters:
        - name: userId
          in: query
          type: string
          required: true
          description: User ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: remove-user-role
        method: DELETE
        description: Remove a role from a user
        inputParameters:
        - name: userId
          in: query
          type: string
          required: true
          description: User ID
        - name: role
          in: query
          type: string
          required: true
          description: Role to remove
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  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: $.