openapi: 3.0.1
info:
  title: Nakama Account Groups 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: Groups
  description: Create and manage groups (clans) and their members.
paths:
  /v2/group:
    post:
      operationId: createGroup
      tags:
      - Groups
      summary: Create a new group with the current user as the owner.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupRequest'
      responses:
        '200':
          description: The newly created group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
  /v2/group/{group_id}/join:
    post:
      operationId: joinGroup
      tags:
      - Groups
      summary: Immediately join an open group, or request to join a closed one.
      parameters:
      - in: path
        name: group_id
        required: true
        schema:
          type: string
        description: The group id to join.
      responses:
        '200':
          description: The user joined or requested to join the group.
components:
  schemas:
    Group:
      type: object
      description: A group in the server.
      properties:
        id:
          type: string
        creator_id:
          type: string
        name:
          type: string
        description:
          type: string
        lang_tag:
          type: string
        metadata:
          type: string
        avatar_url:
          type: string
        open:
          type: boolean
        edge_count:
          type: integer
          format: int32
        max_count:
          type: integer
          format: int32
        create_time:
          type: string
          format: date-time
        update_time:
          type: string
          format: date-time
    CreateGroupRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        description:
          type: string
        lang_tag:
          type: string
        avatar_url:
          type: string
        open:
          type: boolean
          description: Whether the group should have open membership.
        max_count:
          type: integer
          format: int32
  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/