naftiko: 1.0.0-alpha2
info:
  label: Core API — Users
  description: 'Core API — Users. 17 operations. Lead operation: List users. Self-contained Naftiko capability covering one
    Marqeta business surface.'
  tags:
  - Marqeta
  - Users
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    MARQETA_API_KEY: MARQETA_API_KEY
capability:
  consumes:
  - type: http
    namespace: core-users
    baseUri: ''
    description: Core API — Users business capability. Self-contained, no shared references.
    resources:
    - name: users
      path: /users
      operations:
      - name: getusers
        method: GET
        description: List users
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: count
          in: query
          type: integer
          description: Number of user resources to retrieve.
        - name: start_index
          in: query
          type: integer
          description: Sort order index of the first resource in the returned array.
        - name: search_type
          in: query
          type: string
          description: Search type.
        - name: fields
          in: query
          type: string
          description: Comma-delimited list of fields to return (`field_1,field_2`, and so on).
        - name: sort_by
          in: query
          type: string
          description: Field on which to sort.
      - name: postusers
        method: POST
        description: Create user
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: users-auth-changepassword
      path: /users/auth/changepassword
      operations:
      - name: postusersauthchangepassword
        method: POST
        description: Update user password
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: users-auth-clientaccesstoken
      path: /users/auth/clientaccesstoken
      operations:
      - name: postusersauthclientaccesstoken
        method: POST
        description: Create client access token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: users-auth-clientaccesstoken-token
      path: /users/auth/clientaccesstoken/{token}
      operations:
      - name: getusersauthclientaccesstokentoken
        method: GET
        description: Retrieve client access token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: token
          in: path
          type: string
          description: Client access token.
          required: true
        - name: application_token
          in: query
          type: string
          description: Unique identifier of the `application` object.
    - name: users-auth-login
      path: /users/auth/login
      operations:
      - name: postusersauthlogin
        method: POST
        description: Log in user
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: users-auth-logout
      path: /users/auth/logout
      operations:
      - name: postusersauthlogout
        method: POST
        description: Log out user
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: users-auth-onetime
      path: /users/auth/onetime
      operations:
      - name: postusersauthonetime
        method: POST
        description: Create single-use token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: users-auth-resetpassword
      path: /users/auth/resetpassword
      operations:
      - name: postusersauthresetpassword
        method: POST
        description: Request user password reset token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: users-auth-resetpassword-token
      path: /users/auth/resetpassword/{token}
      operations:
      - name: postusersauthresetpasswordtoken
        method: POST
        description: Reset user password
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: token
          in: path
          type: string
          description: Password reset token generated using the `POST /users/auth/resetpassword` operation.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: users-auth-verifyemail
      path: /users/auth/verifyemail
      operations:
      - name: postusersauthverifyemail
        method: POST
        description: Request email verification token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: users-auth-verifyemail-token
      path: /users/auth/verifyemail/{token}
      operations:
      - name: postusersauthverifyemailtoken
        method: POST
        description: Verify email address
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: token
          in: path
          type: string
          description: Email verification token generated using the `POST /users/auth/verifyemail` operation.
          required: true
    - name: users-lookup
      path: /users/lookup
      operations:
      - name: postuserslookup
        method: POST
        description: Search users
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: count
          in: query
          type: integer
          description: Number of user resources to retrieve.
        - name: start_index
          in: query
          type: integer
          description: Sort order index of the first resource in the returned array.
        - name: search_type
          in: query
          type: string
          description: Search type.
        - name: fields
          in: query
          type: string
          description: Comma-delimited list of fields to return (`field_1,field_2`, and so on).
        - name: sort_by
          in: query
          type: string
          description: Field on which to sort.
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: users-parent_token-children
      path: /users/{parent_token}/children
      operations:
      - name: getusersparenttokenchildren
        method: GET
        description: List user child accounts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: count
          in: query
          type: integer
          description: Number of user resources to retrieve.
        - name: start_index
          in: query
          type: integer
          description: Sort order index of the first resource in the returned array.
        - name: parent_token
          in: path
          type: string
          description: Unique identifier of the parent account holder.
          required: true
        - name: fields
          in: query
          type: string
          description: Comma-delimited list of fields to return (`field_1,field_2`, and so on).
        - name: sort_by
          in: query
          type: string
          description: Field on which to sort.
    - name: users-token
      path: /users/{token}
      operations:
      - name: getuserstoken
        method: GET
        description: Retrieve user
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: token
          in: path
          type: string
          description: Unique identifier of the user resource.
          required: true
        - name: fields
          in: query
          type: string
          description: Comma-delimited list of fields to return (`field_1,field_2`, and so on).
      - name: putuserstoken
        method: PUT
        description: Update user
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: token
          in: path
          type: string
          description: Unique identifier of the user resource you want to update.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: users-token-ssn
      path: /users/{token}/ssn
      operations:
      - name: getuserstokenssn
        method: GET
        description: Retrieve user identification number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: token
          in: path
          type: string
          description: Unique identifier of the user resource.
          required: true
        - name: full_ssn
          in: query
          type: boolean
          description: To return the full identification number, set to `true`.
    authentication:
      type: basic
      username: '{{env.MARQETA_USER}}'
      password: '{{env.MARQETA_PASS}}'
  exposes:
  - type: rest
    namespace: core-users-rest
    port: 8080
    description: REST adapter for Core API — Users. One Spectral-compliant resource per consumed operation, prefixed with
      /v1.
    resources:
    - path: /v1/users
      name: users
      description: REST surface for users.
      operations:
      - method: GET
        name: getusers
        description: List users
        call: core-users.getusers
        with:
          count: rest.count
          start_index: rest.start_index
          search_type: rest.search_type
          fields: rest.fields
          sort_by: rest.sort_by
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: postusers
        description: Create user
        call: core-users.postusers
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/auth/changepassword
      name: users-auth-changepassword
      description: REST surface for users-auth-changepassword.
      operations:
      - method: POST
        name: postusersauthchangepassword
        description: Update user password
        call: core-users.postusersauthchangepassword
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/auth/clientaccesstoken
      name: users-auth-clientaccesstoken
      description: REST surface for users-auth-clientaccesstoken.
      operations:
      - method: POST
        name: postusersauthclientaccesstoken
        description: Create client access token
        call: core-users.postusersauthclientaccesstoken
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/auth/clientaccesstoken/{token}
      name: users-auth-clientaccesstoken-token
      description: REST surface for users-auth-clientaccesstoken-token.
      operations:
      - method: GET
        name: getusersauthclientaccesstokentoken
        description: Retrieve client access token
        call: core-users.getusersauthclientaccesstokentoken
        with:
          token: rest.token
          application_token: rest.application_token
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/auth/login
      name: users-auth-login
      description: REST surface for users-auth-login.
      operations:
      - method: POST
        name: postusersauthlogin
        description: Log in user
        call: core-users.postusersauthlogin
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/auth/logout
      name: users-auth-logout
      description: REST surface for users-auth-logout.
      operations:
      - method: POST
        name: postusersauthlogout
        description: Log out user
        call: core-users.postusersauthlogout
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/auth/onetime
      name: users-auth-onetime
      description: REST surface for users-auth-onetime.
      operations:
      - method: POST
        name: postusersauthonetime
        description: Create single-use token
        call: core-users.postusersauthonetime
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/auth/resetpassword
      name: users-auth-resetpassword
      description: REST surface for users-auth-resetpassword.
      operations:
      - method: POST
        name: postusersauthresetpassword
        description: Request user password reset token
        call: core-users.postusersauthresetpassword
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/auth/resetpassword/{token}
      name: users-auth-resetpassword-token
      description: REST surface for users-auth-resetpassword-token.
      operations:
      - method: POST
        name: postusersauthresetpasswordtoken
        description: Reset user password
        call: core-users.postusersauthresetpasswordtoken
        with:
          token: rest.token
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/auth/verifyemail
      name: users-auth-verifyemail
      description: REST surface for users-auth-verifyemail.
      operations:
      - method: POST
        name: postusersauthverifyemail
        description: Request email verification token
        call: core-users.postusersauthverifyemail
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/auth/verifyemail/{token}
      name: users-auth-verifyemail-token
      description: REST surface for users-auth-verifyemail-token.
      operations:
      - method: POST
        name: postusersauthverifyemailtoken
        description: Verify email address
        call: core-users.postusersauthverifyemailtoken
        with:
          token: rest.token
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/lookup
      name: users-lookup
      description: REST surface for users-lookup.
      operations:
      - method: POST
        name: postuserslookup
        description: Search users
        call: core-users.postuserslookup
        with:
          count: rest.count
          start_index: rest.start_index
          search_type: rest.search_type
          fields: rest.fields
          sort_by: rest.sort_by
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/{parent-token}/children
      name: users-parent-token-children
      description: REST surface for users-parent_token-children.
      operations:
      - method: GET
        name: getusersparenttokenchildren
        description: List user child accounts
        call: core-users.getusersparenttokenchildren
        with:
          count: rest.count
          start_index: rest.start_index
          parent_token: rest.parent_token
          fields: rest.fields
          sort_by: rest.sort_by
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/{token}
      name: users-token
      description: REST surface for users-token.
      operations:
      - method: GET
        name: getuserstoken
        description: Retrieve user
        call: core-users.getuserstoken
        with:
          token: rest.token
          fields: rest.fields
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: putuserstoken
        description: Update user
        call: core-users.putuserstoken
        with:
          token: rest.token
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/{token}/ssn
      name: users-token-ssn
      description: REST surface for users-token-ssn.
      operations:
      - method: GET
        name: getuserstokenssn
        description: Retrieve user identification number
        call: core-users.getuserstokenssn
        with:
          token: rest.token
          full_ssn: rest.full_ssn
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: core-users-mcp
    port: 9090
    transport: http
    description: MCP adapter for Core API — Users. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: list-users
      description: List users
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: core-users.getusers
      with:
        count: tools.count
        start_index: tools.start_index
        search_type: tools.search_type
        fields: tools.fields
        sort_by: tools.sort_by
      outputParameters:
      - type: object
        mapping: $.
    - name: create-user
      description: Create user
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: core-users.postusers
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: update-user-password
      description: Update user password
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: core-users.postusersauthchangepassword
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: create-client-access-token
      description: Create client access token
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: core-users.postusersauthclientaccesstoken
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: retrieve-client-access-token
      description: Retrieve client access token
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: core-users.getusersauthclientaccesstokentoken
      with:
        token: tools.token
        application_token: tools.application_token
      outputParameters:
      - type: object
        mapping: $.
    - name: log-user
      description: Log in user
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: core-users.postusersauthlogin
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: log-out-user
      description: Log out user
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: core-users.postusersauthlogout
      outputParameters:
      - type: object
        mapping: $.
    - name: create-single-use-token
      description: Create single-use token
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: core-users.postusersauthonetime
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: request-user-password-reset-token
      description: Request user password reset token
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: core-users.postusersauthresetpassword
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: reset-user-password
      description: Reset user password
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: core-users.postusersauthresetpasswordtoken
      with:
        token: tools.token
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: request-email-verification-token
      description: Request email verification token
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: core-users.postusersauthverifyemail
      outputParameters:
      - type: object
        mapping: $.
    - name: verify-email-address
      description: Verify email address
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: core-users.postusersauthverifyemailtoken
      with:
        token: tools.token
      outputParameters:
      - type: object
        mapping: $.
    - name: search-users
      description: Search users
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: core-users.postuserslookup
      with:
        count: tools.count
        start_index: tools.start_index
        search_type: tools.search_type
        fields: tools.fields
        sort_by: tools.sort_by
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: list-user-child-accounts
      description: List user child accounts
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: core-users.getusersparenttokenchildren
      with:
        count: tools.count
        start_index: tools.start_index
        parent_token: tools.parent_token
        fields: tools.fields
        sort_by: tools.sort_by
      outputParameters:
      - type: object
        mapping: $.
    - name: retrieve-user
      description: Retrieve user
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: core-users.getuserstoken
      with:
        token: tools.token
        fields: tools.fields
      outputParameters:
      - type: object
        mapping: $.
    - name: update-user
      description: Update user
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: core-users.putuserstoken
      with:
        token: tools.token
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: retrieve-user-identification-number
      description: Retrieve user identification number
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: core-users.getuserstokenssn
      with:
        token: tools.token
        full_ssn: tools.full_ssn
      outputParameters:
      - type: object
        mapping: $.