openapi: 3.0.1
info:
  title: Nakama Account 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: Account
  description: Read, update, and delete the current account and link identities.
paths:
  /v2/account:
    get:
      operationId: getAccount
      tags:
      - Account
      summary: Fetch the current user's account.
      responses:
        '200':
          description: The current user's account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
    put:
      operationId: updateAccount
      tags:
      - Account
      summary: Update fields in the current user's account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAccountRequest'
      responses:
        '200':
          description: The account was updated.
    delete:
      operationId: deleteAccount
      tags:
      - Account
      summary: Delete the current user's account.
      responses:
        '200':
          description: The account was deleted.
  /v2/account/link/device:
    post:
      operationId: linkDevice
      tags:
      - Account
      summary: Add a device id to the social profiles on the current user's account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountDevice'
      responses:
        '200':
          description: The device was linked.
  /v2/account/unlink/device:
    post:
      operationId: unlinkDevice
      tags:
      - Account
      summary: Remove a device id from the social profiles on the current user's account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountDevice'
      responses:
        '200':
          description: The device was unlinked.
  /v2/user:
    get:
      operationId: getUsers
      tags:
      - Account
      summary: Fetch zero or more users by id, username, and/or Facebook id.
      parameters:
      - in: query
        name: ids
        schema:
          type: array
          items:
            type: string
        description: The account ids of the users.
      - in: query
        name: usernames
        schema:
          type: array
          items:
            type: string
        description: The account usernames.
      - in: query
        name: facebook_ids
        schema:
          type: array
          items:
            type: string
        description: The Facebook ids of the users.
      responses:
        '200':
          description: A collection of user objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Users'
components:
  schemas:
    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.
    Users:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
    User:
      type: object
      description: A user in the system.
      properties:
        id:
          type: string
          description: The id of the user's account.
        username:
          type: string
        display_name:
          type: string
        avatar_url:
          type: string
        lang_tag:
          type: string
        location:
          type: string
        timezone:
          type: string
        metadata:
          type: string
          description: Additional information stored as a JSON-encoded string.
        facebook_id:
          type: string
        google_id:
          type: string
        apple_id:
          type: string
        steam_id:
          type: string
        online:
          type: boolean
        edge_count:
          type: integer
          format: int32
          description: Number of related edges to this user (friend count).
        create_time:
          type: string
          format: date-time
        update_time:
          type: string
          format: date-time
    Account:
      type: object
      description: A user's full account, including linked identities and wallet.
      properties:
        user:
          $ref: '#/components/schemas/User'
        wallet:
          type: string
          description: The user's wallet data, as a JSON-encoded string.
        email:
          type: string
        devices:
          type: array
          items:
            $ref: '#/components/schemas/AccountDevice'
        custom_id:
          type: string
        verify_time:
          type: string
          format: date-time
        disable_time:
          type: string
          format: date-time
    UpdateAccountRequest:
      type: object
      properties:
        username:
          type: string
        display_name:
          type: string
        avatar_url:
          type: string
        lang_tag:
          type: string
        location:
          type: string
        timezone:
          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/