API docs by Redocly

Pluto API (1.0.0)

Download OpenAPI specification:

License: MIT

Pluto provides a set of HTTP restful APIs for user authentication, authorization, RBAC, and OAuth services.

Authentication

The API uses different authentication mechanisms:

  • No authentication required for public endpoints
  • Access token authentication for user endpoints
  • Admin authentication for administrative endpoints

Error Response

All error responses follow this format:

{
  "status": "error",
  "error": {
    "code": <error_code>,
    "message": "<error_message>"
  }
}

Health Check

API health monitoring

Health check

Check the health status of the API

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": {
    }
}

User Authentication

User registration and authentication

Register user with email

Register a new user account with email

Request Body schema: application/json
required
mail
required
string <email>

User email address

user_id
required
string

Unique user ID

name
required
string

User display name

password
required
string

User password

app_id
required
string

Application ID

Responses

Request samples

Content type
application/json
{
  • "mail": "user@example.com",
  • "user_id": "string",
  • "name": "string",
  • "password": "string",
  • "app_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Send registration verification mail

Send verification email for user registration

Request Body schema: application/json
required
mail
string <email>

User email address

app_id
required
string

Application ID

user_id
string

User ID

Responses

Request samples

Content type
application/json
{
  • "mail": "user@example.com",
  • "app_id": "string",
  • "user_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Login with email or username

Authenticate user with email/username and password

Request Body schema: application/json
required
account
required
string

Email or username

password
required
string

User password

device_id
string

Device identifier

app_id
required
string

Application ID

Responses

Request samples

Content type
application/json
{
  • "account": "string",
  • "password": "string",
  • "device_id": "string",
  • "app_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Login with google account for mobile app

Authenticate user with Google ID token for mobile applications

Request Body schema: application/json
required
id_token
required
string

Google ID token

device_id
string

Device identifier

app_id
required
string

Application ID

Responses

Request samples

Content type
application/json
{
  • "id_token": "string",
  • "device_id": "string",
  • "app_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Login with apple account for mobile app

Authenticate user with Apple authorization code for mobile applications

Request Body schema: application/json
required
code
required
string

Apple authorization code

device_id
string

Device identifier

app_id
required
string

Application ID

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "device_id": "string",
  • "app_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Login with wechat account for web app

Initiate WeChat OAuth flow for web applications

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Login with wechat account for mobile app

Authenticate user with WeChat authorization code for mobile applications

Request Body schema: application/json
required
code
required
string

WeChat authorization code

device_id
string

Device identifier

app_id
required
string

Application ID

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "device_id": "string",
  • "app_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Send password reset mail

Send password reset email to user

Request Body schema: application/json
required
mail
required
string <email>

User email address

app_id
required
string

Application ID

Responses

Request samples

Content type
application/json
{
  • "mail": "user@example.com",
  • "app_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

User Management

User profile and account management

Bind mail, google, wechat, apple account

Bind external accounts to the user profile

Authorizations:
AccessToken
Request Body schema: application/json
required
mail
string <email>

Email to bind

code
string

Authorization code

id_token
string

ID token for social login

type
required
string

Binding type (mail, google, wechat, apple)

Responses

Request samples

Content type
application/json
{
  • "mail": "user@example.com",
  • "code": "string",
  • "id_token": "string",
  • "type": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Unbind mail, google, wechat, apple account

Remove external account binding from user profile

Authorizations:
AccessToken
Request Body schema: application/json
required
type
required
string

Binding type to remove

Responses

Request samples

Content type
application/json
{
  • "type": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Get user info

Get current user's profile information

Authorizations:
AccessToken

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Update user info

Update current user's profile information

Authorizations:
AccessToken
Request Body schema: application/json
required
name
string

User display name

avatar
string

User avatar URL

user_id
string

User ID

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "avatar": "string",
  • "user_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Get user public info like avatar, name

Get public user information

query Parameters
ids
Array of strings

User IDs to fetch

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Get user public info like avatar, name by userId

Get public user information by user ID

path Parameters
userId
required
string

User ID

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Delete user

Delete current user account

Authorizations:
AccessToken

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

User Administration

Administrative user operations

Search the user using name or mail

Search for users by name or email (admin only)

Authorizations:
AdminAuth
query Parameters
name
required
string

Name or email to search for

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Get the summary of users

Get statistical summary of user data (admin only)

Authorizations:
AdminAuth

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

RBAC Management

Role-based access control management

Create role

Create a new role in the application

Authorizations:
AdminAuth
Request Body schema: application/json
required
app_id
required
integer

Application ID

name
required
string

Role name

Responses

Request samples

Content type
application/json
{
  • "app_id": 0,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Create scope

Create a new scope in the application

Authorizations:
AdminAuth
Request Body schema: application/json
required
app_id
required
integer

Application ID

name
required
string

Scope name

Responses

Request samples

Content type
application/json
{
  • "app_id": 0,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Update scopes of the role

Update the scopes assigned to a role

Authorizations:
AdminAuth
Request Body schema: application/json
required
role_id
required
integer

Role ID

scopes
required
Array of integers

Array of scope IDs

Responses

Request samples

Content type
application/json
{
  • "role_id": 0,
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Set the default scope of the role

Set the default scope for a role

Authorizations:
AdminAuth
Request Body schema: application/json
required
role_id
required
integer

Role ID

scope_id
required
integer

Scope ID

Responses

Request samples

Content type
application/json
{
  • "role_id": 0,
  • "scope_id": 0
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Create application

Create a new application

Authorizations:
AdminAuth
Request Body schema: application/json
required
name
required
string

Application name

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": {
    }
}

Update application i18n name

Update internationalized names for the application

Authorizations:
AdminAuth
Request Body schema: application/json
required
app_id
required
integer

Application ID

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "app_id": 0,
  • "i18n_names": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

get application i18n name

Get internationalized name for the application

Authorizations:
AdminAuth
query Parameters
app_id
required
integer

Application ID

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Set the default role of the application

Set the default role for an application

Authorizations:
AdminAuth
Request Body schema: application/json
required
app_id
required
integer

Application ID

role_id
required
integer

Role ID

Responses

Request samples

Content type
application/json
{
  • "app_id": 0,
  • "role_id": 0
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

List all the applications

Get a list of all applications

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": [
    ]
}

List all the roles in the application

Get a list of all roles in a specific application

query Parameters
app_id
required
integer

Application ID

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": {
    }
}

List all the scopes in the application

Get a list of all scopes in a specific application

query Parameters
app_id
required
integer

Application ID

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": {
    }
}

Set the role of a user in application

Assign a role to a user for a specific application

Authorizations:
AdminAuth
Request Body schema: application/json
required
user_id
required
integer

User ID

app_id
required
integer

Application ID

role_id
required
integer

Role ID

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "app_id": 0,
  • "role_id": 0
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Token Management

JWT token operations

Refresh access token

Refresh an access token using a refresh token

Request Body schema: application/json
required
refresh_token
required
string

Refresh token

app_id
required
string

Application ID

scopes
string

Requested scopes

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "string",
  • "app_id": "string",
  • "scopes": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Get the rsa public key

Get the RSA public key for token verification

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": {
    }
}

Verify access token

Verify the validity of an access token

query Parameters
token
required
string

Access token to verify

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

OAuth

OAuth 2.0 operations

Request access token

Request an OAuth access token using various grant types

Request Body schema:
required
grant_type
required
string
Enum: "authorization_code" "password" "client_credentials" "refresh_token"

OAuth grant type

code
string

Authorization code (for authorization_code grant)

redirect_uri
string <uri>

Redirect URI (for authorization_code grant)

scopes
string

Requested scopes

app_id
string

Application ID

device_id
string

Device ID

password
string

User password (for password grant)

user
string

Username (for password grant)

refresh_token
string

Refresh token (for refresh_token grant)

Responses

Request samples

Content type
{
  • "grant_type": "authorization_code",
  • "code": "string",
  • "redirect_uri": "http://example.com",
  • "scopes": "string",
  • "app_id": "string",
  • "device_id": "string",
  • "password": "string",
  • "user": "string",
  • "refresh_token": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Get clients

Get OAuth clients for the authenticated user

Authorizations:
UserAuth

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Create client

Create a new OAuth client

Authorizations:
UserAuth
Request Body schema: application/json
required
key
required
string

Client key

secret
required
string

Client secret

redirect_uri
required
string <uri>

Client redirect URI

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Change the client status

Change the status of an OAuth client (admin only)

Authorizations:
AdminAuth
Request Body schema: application/json
required
key
required
string

Client key

status
required
string

Client status

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "status": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Web Interface

Web-based UI endpoints

Verify the mail registration

Web page for email verification

path Parameters
token
required
string

Verification token

Responses

Reset password page

Web page for password reset

path Parameters
token
required
string

Reset token

Responses

Reset password

Process password reset form submission

path Parameters
token
required
string

Reset token

Request Body schema: application/x-www-form-urlencoded
required
password
required
string

New password

Responses

Oauth authorize page

OAuth authorization page

Authorizations:
AccessToken
query Parameters
client_id
required
string
app_id
required
string
redirect_uri
required
string
response_type
required
string
state
string

Responses

Oauth authorize

Process OAuth authorization

Authorizations:
AccessToken
Request Body schema: application/x-www-form-urlencoded
required
client_id
required
string

OAuth client ID

app_id
required
string

Application ID

redirect_uri
string <uri>

Redirect URI

response_type
required
string
Enum: "code" "token"

OAuth response type

state
string

State parameter

scopes
string

Requested scopes

life_time
integer <int64>

Token lifetime in seconds

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}

Login page

Web login page

query Parameters
app_id
string

Application ID

Responses

Login with email or username

Process web login form

Request Body schema: application/x-www-form-urlencoded
required
account
required
string

Email or username

password
required
string

User password

device_id
string

Device identifier

app_id
required
string

Application ID

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "body": { }
}