Vayana Network Authentication

generated: '2026-09-02'
method: searched
source: https://docs.enriched-api.vayana.com/1s2-integrating/
docs:
- https://docs.enriched-api.vayana.com/1s1-onboarding/
- https://docs.enriched-api.vayana.com/1s2-integrating/
- https://docs.enriched-api.vayana.com/2-encryption-support/
- https://docs.gsp.vayana.com/building-a-vayana-gsp-auth-token/
- https://docs.gsp.vayana.com/generate-keypair/
note: >-
  Derived from the Atlas OpenAPI securitySchemes, then upgraded from Vayana's own published
  integration and encryption documentation, which describes the header scheme the spec's bare
  `bearer` declaration does not capture. All three Vayana programs authenticate against the same
  in-house SSO service, referred to in the docs by its internal name "theodore".
summary:
  types:
  - http
  - apiKey
  identity_provider: Vayana SSO ("theodore")
  transport_encryption: TLS, plus application-layer RSA + AES envelope encryption for sensitive values
schemes:
- name: BearerAuth
  type: http
  scheme: bearer
  in: header
  description: >-
    JWT auth-token issued by the Vayana SSO service, presented as an HTTP Bearer credential.
    This is the scheme declared in the Atlas OpenAPI document.
  sources:
  - openapi/vayana-network-atlas-openapi.json
- name: X-FLYNN-N-USER-TOKEN
  type: apiKey
  in: header
  description: >-
    Enriched API Service (EAS) user token. The base64/plain-text JWT issued by the SSO service at
    login or refresh. Required on every authenticated EAS call.
  sources:
  - https://docs.enriched-api.vayana.com/1s2-integrating/
- name: X-FLYNN-N-ORG-ID
  type: apiKey
  in: header
  description: >-
    Organisation identifier issued by the SSO service at login. Identifies the billed organisation
    on whose behalf the call is made. Required on every authenticated EAS call.
  sources:
  - https://docs.enriched-api.vayana.com/1s2-integrating/
- name: X-FLYNN-S-REK
  type: apiKey
  in: header
  description: >-
    Request Encryption Key. A 32, 48 or 64 character symmetric key generated by the client, itself
    RSA-encrypted (PKCS1Padding) under Vayana's published server public key and sent base64-encoded.
    The server decrypts the REK and uses it to decrypt every X-FLYNN-S-* value in the request.
    A fresh REK per request is the documented recommendation.
  sources:
  - https://docs.enriched-api.vayana.com/1s2-integrating/
  - https://docs.enriched-api.vayana.com/3-downloads/
- name: X-FLYNN-N-*-GSP-CODE
  type: apiKey
  in: header
  description: >-
    GSP identifier under which the taxpayer's portal credentials were created. The only accepted
    value is "vay" (Vay Network Services / Vayana). Sent as X-FLYNN-N-IRP-GSP-CODE for the
    e-invoicing module and X-FLYNN-N-EWB-GSP-CODE for the E-Way Bill module.
  sources:
  - https://docs.enriched-api.vayana.com/components/headers/
- name: government-portal-credentials
  type: apiKey
  in: header
  description: >-
    Per-taxpayer credentials for the downstream government portal, passed through on each call:
    GSTIN, portal username, and password. The password may be sent in plain text
    (X-FLYNN-N-IRP-PWD / X-FLYNN-N-EWB-PWD) or AES-encrypted under the REK
    (X-FLYNN-S-IRP-PWD / X-FLYNN-S-EWB-PWD). This is a delegated-credential model, not
    a Vayana-issued key.
  sources:
  - https://docs.enriched-api.vayana.com/2-encryption-support/
encryption:
  key_exchange: RSA with PKCS1Padding, under a Vayana-published server public key
  public_keys_published: true
  public_key_source: https://docs.enriched-api.vayana.com/3-downloads/
  payload_cipher: AES
  modes:
  - id: ECB
    default: true
    transformation: AES/ECB/PKCS7PADDING
    note: Applied when X-FLYNN-N-AES-ENCRYPTION-MODE is absent.
  - id: CBC
    default: false
    transformation: AES/CBC/PKCS7PADDING
    note: >-
      Selected by sending X-FLYNN-N-AES-ENCRYPTION-MODE=CBC. The initialization vector is sent
      base64-encoded in X-FLYNN-S-IV, itself RSA-encrypted under the EAS server public key.
  header_conventions:
  - prefix: X-FLYNN-N-
    meaning: non-sensitive plain-text header value
  - prefix: X-FLYNN-S-
    meaning: sensitive value, AES-encrypted under the REK and base64-encoded
token_lifecycle:
  issue_operation: POST /theodore/apis/v1/authtokens
  refresh_operation: PUT /theodore/apis/v1/authtokens
  revoke_operation: POST /theodore/apis/v1/logout
  default_duration_minutes: 20
  max_duration_minutes: 360
  duration_parameter: tokenDurationInMins
  hard_session_expiry: 6x the token duration; after hard expiry the token cannot be refreshed and the user must re-authenticate
  max_active_sessions_per_user: 10
  source: https://docs.enriched-api.vayana.com/1s1-onboarding/
sso_endpoints:
- environment: production
  base_url: https://services.vayana.com/theodore/apis/v1
  health: https://services.vayana.com/theodore/apis/health
- environment: sandbox
  base_url: https://sandbox.services.vayananet.com/theodore/apis/v1
  health: https://sandbox.services.vayananet.com/theodore/apis/health
gaps:
- No OAuth 2.0 or OpenID Connect flow is published; there is no authorization-code or
  client-credentials grant and therefore no scope vocabulary.
- The Atlas OpenAPI declares BearerAuth in components.securitySchemes but sets no top-level
  `security` requirement and attaches no `security` block to any of its 65 operations, so the
  contract does not itself state which operations require the token.