Skip to content
Shardkeep

Create an API token

POST
/me/tokens
curl --request POST \
  --url https://example.com/api/v1/me/tokens \
  --header 'Content-Type: application/json' \
  --cookie __Host-shardkeep_session=<__Host-shardkeep_session> \
  --data '{ "name": "example", "permissions": [ "servers.read" ], "expiresAt": "2026-04-15T12:00:00Z" }'

Needs a session: an API token cannot create other tokens. The secret is returned once and never again.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required
string
>= 1 characters <= 100 characters
permissions

Restrict the token to these permissions. Omit for all of yours.

Array<string>
>= 1 items unique items
Allowed values: servers.read servers.create servers.start servers.stop servers.delete servers.console servers.command servers.update files.read files.write files.delete plugins.read plugins.install plugins.update plugins.delete nodes.read nodes.manage backups.read backups.create backups.restore
expiresAt

When the token stops working. Omit for no expiry.

string format: date-time

Responses

Section titled “Responses”

201

Section titled “201”

Token created.

Media typeapplication/json
object
token
required
object
id
required
string format: uuid
name
required
string
displayPrefix
required

The start of the secret, to tell tokens apart.

string
permissions

The token’s permission subset; absent means all of your permissions.

Array<string>
Allowed values: servers.read servers.create servers.start servers.stop servers.delete servers.console servers.command servers.update files.read files.write files.delete plugins.read plugins.install plugins.update plugins.delete nodes.read nodes.manage backups.read backups.create backups.restore
expiresAt
string format: date-time
lastUsedAt
string format: date-time
createdAt
required
string format: date-time
secret
required

The token itself, skp_…. Shown only once.

string
Example
{
  "token": {
    "permissions": [
      "servers.read"
    ]
  }
}

400

Section titled “400”

The request is invalid.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object
type
required
string
title
required
string
status
required
integer
detail
string
code
required

Stable machine-readable error code.

string
Example
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

401

Section titled “401”

Not signed in, or the credentials are invalid.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object
type
required
string
title
required
string
status
required
integer
detail
string
code
required

Stable machine-readable error code.

string
Example
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

403

Section titled “403”

Signed in, but not allowed.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object
type
required
string
title
required
string
status
required
integer
detail
string
code
required

Stable machine-readable error code.

string
Example
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

409

Section titled “409”

Clashes with existing data or state.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object
type
required
string
title
required
string
status
required
integer
detail
string
code
required

Stable machine-readable error code.

string
Example
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

Shardkeep is free software under the AGPL-3.0. Minecraft is a trademark of Mojang AB; Shardkeep is not affiliated with or endorsed by Mojang or Microsoft.