> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create token

> Create and provision a new network token with a card scheme. See [Network Tokens overview](/products/guardian/tokens/network-tokens) for creation sources and supported schemes.

Promoting a wallet token that was already promoted returns `422` with the classifier `WALLET_TOKEN_ALREADY_PROMOTED`; promoting a token that carries no funding PAN (a `CRYPTOGRAM_3DS` token) returns `422` with `UNSUPPORTED_WALLET_TYPE`. See [Promotion](/products/guardian/tokens/wallet-tokens/google-pay#promotion) for eligibility.




## OpenAPI

````yaml /products/guardian/openapi.yaml post /api/network/tokens
openapi: 3.1.0
info:
  title: Guardian API
  version: '1.0'
  contact:
    name: Starfish GmbH & Co. KG
    email: support@hellgate.io
    url: https://hellgate.io/cpa/guardian
  license:
    name: Hellgate API Terms
    url: https://hellgate.io/terms-and-conditions
servers:
  - url: https://{instance}.{env}.on-hellgate.cloud
    description: Managed instance of Guardian
    variables:
      instance:
        default: my-instance
        description: Your unique instance slug, provided during onboarding.
      env:
        default: eu1
        description: Deployment environment (currently eu1).
security: []
tags:
  - name: pci
    description: Management of card payment credentials under the ruling of PCI DSS.
  - name: network
    description: Management of network tokens and cryptograms for secure transactions.
  - name: generic
    description: Management of generic tokens and their schemas for various use cases.
  - name: metadata
    description: Inquiries for card metadata based on PAN, PCI tokens, or network tokens.
  - name: wallet
    description: >-
      Management of wallet tokens ingested from device wallets such as Google
      Pay.
  - name: apikey
    description: Management of API keys for service access.
  - name: webhook
    description: Management of webhooks for event notifications.
  - name: types
    description: Management of types for generic token schemas.
paths:
  /api/network/tokens:
    post:
      tags:
        - network
      summary: Create token
      description: >
        Create and provision a new network token with a card scheme. See
        [Network Tokens overview](/products/guardian/tokens/network-tokens) for
        creation sources and supported schemes.


        Promoting a wallet token that was already promoted returns `422` with
        the classifier `WALLET_TOKEN_ALREADY_PROMOTED`; promoting a token that
        carries no funding PAN (a `CRYPTOGRAM_3DS` token) returns `422` with
        `UNSUPPORTED_WALLET_TYPE`. See
        [Promotion](/products/guardian/tokens/wallet-tokens/google-pay#promotion)
        for eligibility.
      operationId: network_token_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/network_token_create_request'
            examples:
              session:
                summary: Session as Source (SAQ-A+)
                value:
                  source:
                    type: session
              pan:
                summary: PAN as Source (SAQ-D+)
                value:
                  source:
                    type: pan
                    account_number: '4111111111111111'
                    expiry_month: 12
                    expiry_year: 2025
                    security_code: '123'
              pci_token:
                summary: PCI Token as Source (SAQ-A+)
                value:
                  source:
                    type: pci_token
                    pci_token_id: 123e4567-e89b-12d3-a456-426614174000
              wallet_token:
                summary: Wallet Token as Source (SAQ-A+)
                value:
                  source:
                    type: wallet_token
                    wallet_token_id: 0d5c1774-5f3f-4a2f-9c86-1f30a0ea9be2
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/network_token_create_response'
              examples:
                session:
                  summary: Session as Source (SAQ-A+)
                  value:
                    session_id: 6a3342be-1b50-4d3e-b430-708dfcd5967a
                pan:
                  summary: PAN as Source (SAQ-D+)
                  value:
                    id: 123e4567-e89b-12d3-a456-426614174000
                    card:
                      cardholder_name: John Doe
                      expiry_month: 12
                      expiry_year: 2025
                      masked_account_number: 411111******1111
                      scheme: visa
                    created_at: '2023-10-01T12:00:00Z'
                    network_token:
                      status: active
                      type: vts
                pci_token:
                  summary: PCI Token as Source (SAQ-A+)
                  value:
                    id: 123e4567-e89b-12d3-a456-426614174000
                    card:
                      cardholder_name: John Doe
                      expiry_month: 12
                      expiry_year: 2025
                      masked_account_number: 411111******1111
                      scheme: visa
                    created_at: '2023-10-01T12:00:00Z'
                    network_token:
                      status: active
                      type: vts
                wallet_token:
                  summary: Wallet Token as Source (SAQ-A+)
                  value:
                    source:
                      type: wallet_token
                      wallet_token_id: 0d5c1774-5f3f-4a2f-9c86-1f30a0ea9be2
                    network_token:
                      id: 123e4567-e89b-12d3-a456-426614174000
                      scheme: visa
                      expiry_month: 12
                      expiry_year: 2028
                      type: vts
                      status: active
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '409':
          $ref: '#/components/responses/409_ConflictError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
      security:
        - bearerAuth: []
        - APIKey: []
components:
  schemas:
    network_token_create_request:
      type: object
      properties:
        source:
          type: object
          oneOf:
            - $ref: '#/components/schemas/from_session_source'
            - $ref: '#/components/schemas/from_pan_source'
            - $ref: '#/components/schemas/from_pci_token_source'
            - $ref: '#/components/schemas/from_wallet_token_source'
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - source
    network_token_create_response:
      type: object
      oneOf:
        - $ref: '#/components/schemas/session'
        - $ref: '#/components/schemas/network_token'
        - $ref: '#/components/schemas/wallet_token_promotion_response'
    from_session_source:
      title: From Session
      type: object
      properties:
        type:
          type: string
          enum:
            - session
      required:
        - type
    from_pan_source:
      title: From PAN
      type: object
      properties:
        type:
          type: string
          enum:
            - pan
        account_number:
          type: string
          description: The card number (without separators)
          example: '4111111111111111'
        cardholder_name:
          type: string
          description: The name of the cardholder
          example: Bob Holder
        expiry_year:
          type: integer
          description: The expiry year of the card
          minimum: 2000
          example: 2025
        expiry_month:
          type: integer
          description: The expiry month of the card
          minimum: 1
          maximum: 12
          example: 4
        security_code:
          type: string
          minLength: 3
          maxLength: 4
          example: '321'
          description: >
            The security code of the card. The system does not permanently store
            the security code; it is kept in an ephemeral position for immediate
            use.
      required:
        - type
        - account_number
        - expiry_year
        - expiry_month
    from_pci_token_source:
      title: From PCI Token
      type: object
      properties:
        type:
          type: string
          enum:
            - pci_token
        pci_token_id:
          example: 5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d
          type: string
          format: uuid
      required:
        - type
        - pci_token_id
    from_wallet_token_source:
      title: From Wallet Token
      type: object
      description: >
        Promote a `PAN_ONLY` wallet token to a network token. See [Wallet
        Tokens](/products/guardian/tokens/wallet-tokens/google-pay#promotion).
      properties:
        type:
          type: string
          enum:
            - wallet_token
        wallet_token_id:
          example: 8a1e6c2b-7f30-4b9d-a2c5-4e8f1b6d9c30
          type: string
          format: uuid
      required:
        - type
        - wallet_token_id
    Metadata:
      type: object
      description: |
        Metadata consisting of key-value entries.

          * Maximum 20 key-value pairs.
          * Maximum 20 characters per key.
          * Maximum 80 characters per value.
      example:
        my_key_one: my_value_one
        my_key_two: my_value_two
    session:
      title: Session
      type: object
      properties:
        session_id:
          example: 0f2c8f7e-4d2a-4d1b-9a6e-1c9b2d3e4f50
          type: string
          format: uuid
      required:
        - session_id
    network_token:
      type: object
      properties:
        id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          format: uuid
        card:
          $ref: '#/components/schemas/card'
        created_at:
          example: '2023-10-01T12:00:00Z'
          type: string
          format: date-time
        network_token:
          type: object
          properties:
            scheme_reference:
              example: '790123456789'
              type: string
              description: >
                The ID of the network token at the scheme. 


                This value is only present if Delegated Authentication is active
                for the instance.
            status:
              type: string
              enum:
                - active
                - inactive
                - deleted
            type:
              type: string
              description: The network token type.
              enum:
                - vts
                - mdes
                - tms
          required:
            - status
            - type
        pci_token_id:
          type: string
          format: uuid
          description: The ID of the PCI token that represents the `card`
        metadata:
          $ref: '#/components/schemas/Metadata'
          example:
            order_ref: order-1234567890
      required:
        - id
        - card
        - created_at
        - network_token
      example:
        id: 123e4567-e89b-12d3-a456-426614174000
        created_at: '2023-10-01T12:00:00Z'
        card:
          cardholder_name: John Doe
          expiry_month: 12
          expiry_year: 2025
          masked_account_number: 411111******1111
          scheme: visa
        network_token:
          status: active
          type: vts
        pci_token_id: 42510fee-ee8a-4377-a6e9-8aca381578ea
    wallet_token_promotion_response:
      title: Wallet Token Promotion
      type: object
      description: >
        Returned when a network token is created from a `wallet_token` source.
        Guardian vaults the wallet token's funding PAN as a PCI token,
        provisions the network token from it, and records the link on the wallet
        token's `promoted_to` field.
      properties:
        source:
          $ref: '#/components/schemas/from_wallet_token_source'
        network_token:
          type: object
          properties:
            id:
              type: string
              format: uuid
            scheme:
              type: string
              example: visa
            expiry_month:
              type: integer
            expiry_year:
              type: integer
            type:
              type: string
              description: The network token type.
              enum:
                - vts
                - mdes
                - tms
            status:
              type: string
              enum:
                - active
                - inactive
                - deleted
                - unprovisioned
          required:
            - id
            - scheme
            - expiry_month
            - expiry_year
            - type
            - status
      required:
        - source
        - network_token
      example:
        source:
          type: wallet_token
          wallet_token_id: 0d5c1774-5f3f-4a2f-9c86-1f30a0ea9be2
        network_token:
          id: 123e4567-e89b-12d3-a456-426614174000
          scheme: visa
          expiry_month: 12
          expiry_year: 2028
          type: vts
          status: active
    ErrorGeneric:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorStatusCode'
        classifier:
          $ref: '#/components/schemas/ErrorClassifier'
        message:
          $ref: '#/components/schemas/ErrorMessage'
    ErrorValidation:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorStatusCode'
        classifier:
          $ref: '#/components/schemas/ErrorClassifier'
        message:
          $ref: '#/components/schemas/ErrorMessage'
        validation_errors:
          type: array
          items:
            type: object
            properties:
              path:
                example: $.source.account_number
                type: string
                description: Json-path in the request which points to the validation error
              message:
                example: is required
                type: string
                description: Human readable validation message
    card:
      type: object
      properties:
        cardholder_name:
          type: string
        expiry_month:
          type: integer
        expiry_year:
          type: integer
        masked_account_number:
          type: string
        scheme:
          type: string
          enum:
            - visa
            - mastercard
            - american express
            - discover
            - diners club
            - jcb
            - unionpay
      required:
        - expiry_month
        - expiry_year
        - masked_account_number
        - scheme
      example:
        cardholder_name: John Doe
        expiry_month: 12
        expiry_year: 2025
        masked_account_number: 411111******1111
        scheme: visa
    ErrorStatusCode:
      type: integer
      description: The corresponding HTTP status code for the error
    ErrorClassifier:
      type: string
      description: Technical code that helps to identify the error
    ErrorMessage:
      type: string
      description: Human readable representation of the error
  responses:
    401_UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 401
            message: No valid means of authentication was provided
            classifier: UNAUTHORIZED
    403_ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 403
            message: Not allowed to access this resource or feature
            classifier: FORBIDDEN
    409_ConflictError:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 409
            message: Conflict
            classifier: CONFLICT
    422_ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorValidation'
          example:
            code: 422
            classifier: VALIDATION_ERROR
            message: Validation error
            validation_errors:
              - path: json-path
                message: human readable error message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT bearer token obtained via the OAuth2 client-credentials grant from
        the platform Authentication API. The token's scopes gate the endpoints
        it may call, and its audience names the Guardian instance. This is the
        standard way to authenticate to Guardian.
    APIKey:
      type: apiKey
      name: x-api-key
      in: header
      description: >-
        Deprecated. Long-lived instance API key, sent as `x-api-key`. Existing
        integrations continue to work, but new ones should use the OAuth2 bearer
        token instead.

````