openapi: 3.0.1
info:
  title: Nakama Account Authentication API
  description: 'Representative OpenAPI description of the core REST API for Nakama, the open-source game and app backend server by Heroic Labs. Nakama''s public HTTP API is generated by the gRPC-gateway from `api/api.proto` and is published upstream as `apigrpc/apigrpc.swagger.json` in the heroiclabs/nakama repository. This document reconstructs the primary client-facing surface: authentication, accounts and identity linking, social (friends and groups), storage, leaderboards and tournaments, notifications, and custom RPCs.


    Authentication endpoints are guarded by the server key using HTTP Basic auth, where the server key is the username and the password is empty. All other endpoints are authorized with the JWT session token returned by an authenticate call, sent as `Authorization: Bearer <session_token>`. RPC endpoints may alternatively be called server-to-server with an `http_key` query parameter.'
  termsOfService: https://heroiclabs.com/terms/
  contact:
    name: Heroic Labs
    url: https://heroiclabs.com/
    email: support@heroiclabs.com
  license:
    name: Apache 2.0
    url: https://github.com/heroiclabs/nakama/blob/master/LICENSE
  version: '2.0'
servers:
- url: http://127.0.0.1:7350
  description: Default self-hosted Nakama server. Replace host/port with your Heroic Cloud project URL in production.
security:
- BearerAuth: []
tags:
- name: Authentication
  description: Authenticate users and issue or refresh session tokens.
paths:
  /v2/account/authenticate/device:
    post:
      operationId: authenticateDevice
      tags:
      - Authentication
      summary: Authenticate a user with a device id against the server.
      security:
      - BasicAuth: []
      parameters:
      - in: query
        name: create
        schema:
          type: boolean
        description: Register the account if the user does not already exist.
      - in: query
        name: username
        schema:
          type: string
        description: Set the username on the account at register. Ignored if the account exists.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateDeviceRequest'
      responses:
        '200':
          description: A session with the current session token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
  /v2/account/authenticate/email:
    post:
      operationId: authenticateEmail
      tags:
      - Authentication
      summary: Authenticate a user with an email and password against the server.
      security:
      - BasicAuth: []
      parameters:
      - in: query
        name: create
        schema:
          type: boolean
      - in: query
        name: username
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateEmailRequest'
      responses:
        '200':
          description: A session with the current session token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
  /v2/account/authenticate/custom:
    post:
      operationId: authenticateCustom
      tags:
      - Authentication
      summary: Authenticate a user with a custom id against the server.
      security:
      - BasicAuth: []
      parameters:
      - in: query
        name: create
        schema:
          type: boolean
      - in: query
        name: username
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateCustomRequest'
      responses:
        '200':
          description: A session with the current session token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
  /v2/account/session/refresh:
    post:
      operationId: sessionRefresh
      tags:
      - Authentication
      summary: Refresh a user's session using a refresh token retrieved from a previous authentication request.
      security:
      - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionRefreshRequest'
      responses:
        '200':
          description: A session with a new session token and refresh token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
components:
  schemas:
    AuthenticateDeviceRequest:
      type: object
      properties:
        account:
          $ref: '#/components/schemas/AccountDevice'
        create:
          type: boolean
        username:
          type: string
    AccountCustom:
      type: object
      description: Send a custom id to the server.
      required:
      - id
      properties:
        id:
          type: string
          description: A custom identifier. Must be between 6 and 128 bytes.
        vars:
          type: object
          additionalProperties:
            type: string
    SessionRefreshRequest:
      type: object
      properties:
        token:
          type: string
          description: Refresh token.
        vars:
          type: object
          additionalProperties:
            type: string
          description: Extra information passed to the identity providers.
    AccountDevice:
      type: object
      description: Send a device to the server. Used with authenticate/link/unlink and register.
      required:
      - id
      properties:
        id:
          type: string
          description: A device identifier. Must be between 10 and 128 bytes.
        vars:
          type: object
          additionalProperties:
            type: string
          description: Extra information stored on the session.
    AuthenticateEmailRequest:
      type: object
      properties:
        account:
          $ref: '#/components/schemas/AccountEmail'
        create:
          type: boolean
        username:
          type: string
    Session:
      type: object
      description: A user's session used to authenticate messages.
      properties:
        created:
          type: boolean
          description: True if the corresponding account was just created, false otherwise.
        token:
          type: string
          description: Authentication credentials (JWT session token).
        refresh_token:
          type: string
          description: Refresh token that can be used to renew a session.
    AuthenticateCustomRequest:
      type: object
      properties:
        account:
          $ref: '#/components/schemas/AccountCustom'
        create:
          type: boolean
        username:
          type: string
    AccountEmail:
      type: object
      description: Send an email with password to the server.
      required:
      - email
      - password
      properties:
        email:
          type: string
          description: A valid RFC-5322 email address.
        password:
          type: string
          description: A password, at least 8 characters long.
        vars:
          type: object
          additionalProperties:
            type: string
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auth using the server key as the username and an empty password. Guards the authenticate endpoints.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'The JWT session token returned by an authenticate call, sent as `Authorization: Bearer <session_token>`.'
externalDocs:
  description: Nakama documentation
  url: https://heroiclabs.com/docs/nakama/