> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postcode.gov.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Start an embeddable-widget session

> Exchanges a publishable key + user identifier (NIN or email) for a short-lived widget token. Always responds 200 with a token; an unknown identifier yields a valid session that simply has zero bookmarks, so callers cannot probe which identifiers exist. Served by the platform host, not the gateway.



## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/widget/session
openapi: 3.1.0
info:
  title: NIPOST Postcode Gateway — Public API
  version: 0.1.0
  description: >
    Public API for Nigeria's national postcode system. Search and Lookup L1 are
    free; Lookup L2–L4 are commercial (credits); L5 is restricted. Authenticate
    with an API key.
servers:
  - url: https://api.postcode.gov.ng
    description: Production
  - url: http://localhost:8081
    description: Local gateway
security:
  - ApiKeyAuth: []
paths:
  /v1/widget/session:
    post:
      summary: Start an embeddable-widget session
      description: >-
        Exchanges a publishable key + user identifier (NIN or email) for a
        short-lived widget token. Always responds 200 with a token; an unknown
        identifier yields a valid session that simply has zero bookmarks, so
        callers cannot probe which identifiers exist. Served by the platform
        host, not the gateway.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - identifier_type
                - identifier
              properties:
                identifier_type:
                  type: string
                  enum:
                    - nin
                    - email
                identifier:
                  type: string
                  example: ada@example.com
      responses:
        '200':
          description: Widget session token
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/WidgetSession'
        '401':
          description: Missing, invalid or revoked publishable key
        '402':
          description: Insufficient credits
        '403':
          description: Key is not publishable/widget-scoped, or origin not allowed
        '422':
          description: Bad identifier_type or empty identifier
        '429':
          description: Rate limited
      security:
        - PublishableKey: []
      servers:
        - url: https://platform.postcode.gov.ng
          description: Production platform
        - url: http://localhost:8082
          description: Local platform
components:
  schemas:
    WidgetSession:
      type: object
      properties:
        token:
          type: string
          description: Bearer token for the widget endpoints
        expires_in:
          type: integer
          example: 900
          description: Seconds until expiry
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    PublishableKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Publishable key (nipost_pk_…) with the widget scope

````