Reads, writes, lists, and deletes JSON storage objects organized into collections and keyed per user, with per-object owner and public read/write permissions and optimistic-concurrency version checks. Backs save games, inventories, and shared app state.
openapi: 3.0.1
info:
title: Nakama 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'
externalDocs:
description: Nakama documentation
url: https://heroiclabs.com/docs/nakama/
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.
tags:
- name: Authentication
description: Authenticate users and issue or refresh session tokens.
- name: Account
description: Read, update, and delete the current account and link identities.
- name: Friends
description: Manage the friend graph.
- name: Groups
description: Create and manage groups (clans) and their members.
- name: Storage
description: Read, write, list, and delete storage objects.
- name: Leaderboards
description: Write and list leaderboard records.
- name: Tournaments
description: List, join, and submit to tournaments.
- name: Notifications
description: List and delete in-app notifications.
- name: RPC
description: Call custom runtime functions.
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'
/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'
/v2/friend:
get:
operationId: listFriends
tags:
- Friends
summary: List all friends for the current user.
parameters:
- in: query
name: limit
schema:
type: integer
format: int32
description: Max number of records to return. Between 1 and 1000.
- in: query
name: state
schema:
type: integer
format: int32
description: 'The friend state to list - 0 friends, 1 invite sent, 2 invite received, 3 blocked.'
- in: query
name: cursor
schema:
type: string
description: An optional next page cursor.
responses:
'200':
description: A collection of zero or more friends of the user.
content:
application/json:
schema:
$ref: '#/components/schemas/FriendList'
post:
operationId: addFriends
tags:
- Friends
summary: Add friends by ids or usernames.
parameters:
- in: query
name: ids
schema:
type: array
items:
type: string
description: The account ids of the users to add as friends.
- in: query
name: usernames
schema:
type: array
items:
type: string
description: The usernames of the users to add as friends.
responses:
'200':
description: The friends were added or invited.
delete:
operationId: deleteFriends
tags:
- Friends
summary: Delete one or more friends for the current user.
parameters:
- in: query
name: ids
schema:
type: array
items:
type: string
- in: query
name: usernames
schema:
type: array
items:
type: string
responses:
'200':
description: The friends were deleted.
/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.
/v2/storage:
put:
operationId: writeStorageObjects
tags:
- Storage
summary: Write objects into the storage engine.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WriteStorageObjectsRequest'
responses:
'200':
description: Acknowledgements of the written objects.
content:
application/json:
schema:
$ref: '#/components/schemas/StorageObjectAcks'
post:
operationId: readStorageObjects
tags:
- Storage
summary: Get objects from the storage engine.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ReadStorageObjectsRequest'
responses:
'200':
description: A list of storage objects.
content:
application/json:
schema:
$ref: '#/components/schemas/StorageObjects'
/v2/storage/{collection}:
get:
operationId: listStorageObjects
tags:
- Storage
summary: List publicly readable storage objects in a given collection.
parameters:
- in: path
name: collection
required: true
schema:
type: string
description: The collection to list over.
- in: query
name: user_id
schema:
type: string
description: The user id of the storage objects to list. Set empty to list all users.
- in: query
name: limit
schema:
type: integer
format: int32
- in: query
name: cursor
schema:
type: string
responses:
'200':
description: A list of storage objects.
content:
application/json:
schema:
$ref: '#/components/schemas/StorageObjectList'
/v2/storage/delete:
put:
operationId: deleteStorageObjects
tags:
- Storage
summary: Delete one or more objects by id or username.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteStorageObjectsRequest'
responses:
'200':
description: The objects were deleted.
/v2/leaderboard/{leaderboard_id}:
get:
operationId: listLeaderboardRecords
tags:
- Leaderboards
summary: List records from a leaderboard.
parameters:
- in: path
name: leaderboard_id
required: true
schema:
type: string
description: The leaderboard id.
- in: query
name: owner_ids
schema:
type: array
items:
type: string
description: One or more owners to retrieve records for.
- in: query
name: limit
schema:
type: integer
format: int32
- in: query
name: cursor
schema:
type: string
responses:
'200':
description: A list of leaderboard records.
content:
application/json:
schema:
$ref: '#/components/schemas/LeaderboardRecordList'
post:
operationId: writeLeaderboardRecord
tags:
- Leaderboards
summary: Write a record to a leaderboard.
parameters:
- in: path
name: leaderboard_id
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WriteLeaderboardRecordRequest'
responses:
'200':
description: The written leaderboard record.
content:
application/json:
schema:
$ref: '#/components/schemas/LeaderboardRecord'
/v2/tournament:
get:
operationId: listTournaments
tags:
- Tournaments
summary: List current or upcoming tournaments.
parameters:
- in: query
name: category_start
schema:
type: integer
format: int32
- in: query
name: category_end
schema:
type: integer
format: int32
- in: query
name: limit
schema:
type: integer
format: int32
- in: query
name: cursor
schema:
type: string
responses:
'200':
description: A list of tournaments.
content:
application/json:
schema:
$ref: '#/components/schemas/TournamentList'
/v2/tournament/{tournament_id}/join:
post:
operationId: joinTournament
tags:
- Tournaments
summary: Attempt to join an open and running tournament.
parameters:
- in: path
name: tournament_id
required: true
schema:
type: string
responses:
'200':
description: The user joined the tournament.
/v2/notification:
get:
operationId: listNotifications
tags:
- Notifications
summary: Fetch a list of notifications.
parameters:
- in: query
name: limit
schema:
type: integer
format: int32
description: The number of notifications to get. Between 1 and 100.
- in: query
name: cacheable_cursor
schema:
type: string
description: A cursor to page through notifications, usually cached client-side.
responses:
'200':
description: A collection of notifications.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationList'
delete:
operationId: deleteNotifications
tags:
- Notifications
summary: Delete one or more notifications for the current user.
parameters:
- in: query
name: ids
schema:
type: array
items:
type: string
description: The id of notifications to delete.
responses:
'200':
description: The notifications were deleted.
/v2/rpc/{id}:
post:
operationId: rpcFunc
tags:
- RPC
summary: Execute a Nakama runtime RPC function with a session token.
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The identifier of the runtime function.
- in: query
name: http_key
schema:
type: string
description: The runtime http_key for server-to-server calls, in place of a session token.
requestBody:
required: true
content:
application/json:
schema:
type: string
description: The payload passed to the function, as a JSON-encoded string.
responses:
'200':
description: The payload returned from the function.
content:
application/json:
schema:
$ref: '#/components/schemas/Rpc'
get:
operationId: rpcFunc2
tags:
- RPC
summary: Execute a Nakama runtime RPC function with an http key or session token.
parameters:
- in: path
name: id
required: true
schema:
type: string
- in: query
name: payload
schema:
type: string
description: The payload for the function, as a URL-encoded string.
- in: query
name: http_key
schema:
type: string
responses:
'200':
description: The payload returned from the function.
content:
application/json:
schema:
$ref: '#/components/schemas/Rpc'
components:
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>`.
schemas:
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.
AuthenticateDeviceRequest:
type: object
properties:
account:
$ref: '#/components/schemas/AccountDevice'
create:
type: boolean
username:
type: string
AuthenticateEmailRequest:
type: object
properties:
account:
$ref: '#/components/schemas/AccountEmail'
create:
type: boolean
username:
type: string
AuthenticateCustomRequest:
type: object
properties:
account:
$ref: '#/components/schemas/AccountCustom'
create:
type: boolean
username:
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.
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
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
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
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
Users:
type: object
properties:
users:
type: array
items:
$ref: '#/components/schemas/User'
Friend:
type: object
description: A friend of a user.
properties:
user:
$ref: '#/components/schemas/User'
state:
type: integer
format: int32
description: 'The friend status - 0 mutual, 1 invite sent, 2 invite received, 3 blocked.'
update_time:
type: string
format: date-time
FriendList:
type: object
properties:
friends:
type: array
items:
$ref: '#/components/schemas/Friend'
cursor:
type: string
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
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
StorageObject:
type: object
description: An object within the storage engine.
properties:
collection:
type: string
description: The collection which stores the object.
key:
type: string
description: The key of the object within the collection.
user_id:
type: string
description: The user owner of the object.
value:
type: string
description: The value of the object, a JSON-encoded string.
version:
type: string
description: The version hash of the object, for optimistic concurrency.
permission_read:
type: integer
format: int32
description: '0 no read, 1 owner read, 2 public read.'
permission_write:
type: integer
format: int32
description: '0 no write, 1 owner write.'
create_time:
type: string
format: date-time
update_time:
type: string
format: date-time
WriteStorageObject:
type: object
required:
- collection
- key
- value
properties:
collection:
type: string
key:
type: string
value:
type: string
version:
type: string
permission_read:
type: integer
format: int32
permission_write:
type: integer
format: int32
WriteStorageObjectsRequest:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/WriteStorageObject'
ReadStorageObjectId:
type: object
required:
- collection
- key
properties:
collection:
type: string
key:
type: string
user_id:
type: string
ReadStorageObjectsRequest:
type: object
properties:
object_ids:
type: array
items:
$ref: '#/components/schemas/ReadStorageObjectId'
DeleteStorageObjectId:
type: object
required:
- collection
- key
properties:
collection:
type: string
key:
type: string
version:
type: string
DeleteStorageObjectsRequest:
type: object
properties:
object_ids:
type: array
items:
$ref: '#/components/schemas/DeleteStorageObjectId'
StorageObjects:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/StorageObject'
StorageObjectList:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/StorageObject'
cursor:
type: string
StorageObjectAck:
type: object
properties:
collection:
type: string
key:
type: string
version:
type: string
user_id:
type: string
StorageObjectAcks:
type: object
properties:
acks:
type: array
items:
$ref: '#/components/schemas/StorageObjectAck'
LeaderboardRecord:
type: object
description: Represents a complete leaderboard record with all scores and associated metadata.
properties:
leaderboard_id:
type: string
owner_id:
type: string
username:
type: string
score:
type: string
format: int64
subscore:
type: string
format: int64
num_score:
type: integer
format: int32
metadata:
type: string
create_time:
type: string
format: date-time
update_time:
type: string
format: date-time
expiry_time:
type: string
format: date-time
rank:
type: string
format: int64
WriteLeaderboardRecordRequest:
type: object
properties:
score:
type: string
format: int64
subscore:
type: string
format: int64
metadata:
type: string
LeaderboardRecordList:
type: object
properties:
records:
type: array
items:
$ref: '#/components/schemas/LeaderboardRecord'
owner_records:
type: array
items:
$ref: '#/components/schemas/LeaderboardRecord'
next_cursor:
type: string
prev_cursor:
type: string
Tournament:
type: object
properties:
id:
type: string
title:
type: string
description:
type: string
category:
type: integer
format: int32
sort_order:
type: integer
format: int32
size:
type: integer
format: int32
max_size:
type: integer
format: int32
max_num_score:
type: integer
format: int32
can_enter:
type: boolean
end_active:
type: integer
format: int32
next_reset:
type: integer
format: int32
duration:
type: integer
format: int32
start_time:
type: string
format: date-time
end_time:
type: string
format: date-time
TournamentList:
type: object
properties:
tournaments:
type: array
items:
$ref: '#/components/schemas/Tournament'
cursor:
type: string
Notification:
type: object
description: A notification in the server.
properties:
id:
type: string
subject:
type: string
content:
type: string
description: Content payload, a JSON-encoded string.
code:
type: integer
format: int32
description:
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nakama/refs/heads/main/openapi/nakama-openapi.yml