User

Retrieve Additional User Data

Returns supplementary data for the token owner, such as the number of projects they have created.

Request

POST /api/permissions/user/info

Warning

Passing jwt, factor, and service_jwt in the request body is deprecated. Use the corresponding HTTP headers instead.

  • jwt string required

    User’s JWT token.

  • factor string conditionally required

    User device factor. Required if service_jwt is not provided.

  • service_jwt string conditionally required

    Service JWT. Required if factor is not provided.

Request example
POST /api/permissions/user/info
Headers
Authorization: Bearer eyJhbGci...
Factor: ...

Response

Success

  • status string required

    • “OK”

  • projects integer required

    The number of projects where the user (token owner) is the author.

Response example
{
  "status": "OK",
  "projects": 5
}

Error

  • status string required

    • “ERROR”

  • error string required

    Descriptive error message.

Response example
{
  "status": "ERROR",
  "error": "invalid token"
}

Retrieve and Edit User Schema

Retrieves or updates the permission schema for a specific user and application.

Access Requirements

To read or update the user schema, the request author must have the following permissions for the respective sections:

  • secret_data.meta.public.canRead or canWrite — for public_data

  • secret_data.meta.private.canRead or canWrite — for private_data

  • secret_data.meta.secret.canRead or canWrite — for secret_data

  • secret_data.meta.roles.canRead or canWrite — for roles

Service accounts for the project associated with the application are also allowed.

If user_id is not provided or matches the uid from the user’s JWT, the permissions are returned without restriction.

Note

If application_id is missing from the request but a service_jwt is provided, the application ID will be extracted from the token.

When service_jwt is provided, expired user JWTs are accepted, and factor validation is skipped. To request without any user JWT, provide a service token in service_jwt or an access key in the Authorization: Bearer header.

Even if a user has never logged into an application, their schema can be saved in advance.

Request

POST /api/permissions/meta/data

Warning

Passing jwt, factor, and service_jwt in the request body is deprecated. Use the corresponding HTTP headers instead.

  • jwt string required

    User’s JWT token. Expired tokens are accepted when service_jwt is provided.

  • factor string optional

    User device factor. Required only when neither service_jwt nor an access key is provided.

  • service_jwt string optional

    Service JWT. When provided, bypasses factor validation and allows expired user JWTs.

  • action string required

    Action to perform. Allowed values: "get", "save".

  • application_id string or integer required

    ID of the application for which the user schema is being retrieved or edited.

  • data object required

    • user_id string required

      ID of the user whose schema is being retrieved or edited.

    • type string optional

      Schema format for "get". Allowed values: "tree", "list", "list_short", "roles". See Schema Types.

  • options object optional

    Additional filters for the "get" action.

    • project_id string optional

      Filters the response to include only root rules and rules for the given project.

    • hide_project_access boolean optional

      If true, excludes project access information and returns only root rules. Defaults to false.

    • with_exp boolean optional

      If true, appends the TTL in seconds to each rule after a colon (e.g., "login.can:7200"). A value of 0 means no expiration. Defaults to false.

    • with_roles boolean optional

      If true, the response data field includes rules and roles. Defaults to false.

    • with_apps_data boolean optional

      If true, the response data field includes rules, projects, and apps. Defaults to false.

  • expired integer optional

    Expiration timestamp in Unix epoch format. Used for the "save" action.

Request example
POST /api/permissions/meta/data
Headers
Authorization: Bearer eyJhbGci...
Factor: ...
Body (get)
{
  "action": "get",
  "application_id": 50001,
  "data": {
    "user_id": "12345",
    "type": "list_short"
  },
  "options": {
    "project_id": "warthunder",
    "with_exp": true
  }
}
Body (save)
{
  "action": "save",
  "application_id": 50001,
  "data": {
    "user_id": "12345",
    "roles": ["writer"],
    "private_data": {
      "canManageTags": {"value": true, "params": "internal,game"}
    }
  }
}

Response

Success

  • status string required

    • “OK”

  • data array or object required

    The schema content. Format depends on the type parameter and the options provided. For the "save" action, returns the updated schema in "tree" format (see Schema Types).

    When neither with_roles nor with_apps_data is enabled, data is an array of strings. When either option is true, data becomes an object with the following fields:

    • rules array of strings required

      List of permissions assigned to the user. Present when with_roles or with_apps_data is true.

    • roles array of strings optional

      List of roles assigned to the user. Present when with_roles is true.

    • projects object optional

      Map of projects the user has access to, keyed by project ID. Present when with_apps_data is true. Each value is an object with:

      • name string required

        Project display name.

      • aliases array of strings optional

        Alternative project identifiers. Omitted if none are defined.

    • apps object optional

      Map of applications associated with the user’s project access, keyed by project ID. Present when with_apps_data is true. Each value is an array of objects with:

      • id integer required

        Application ID.

      • name string required

        Application display name.

  • user_id string required

    The ID of the requested user.

  • expired integer required

    Expiration timestamp in Unix epoch format. 0 if not time-limited.

Response example
{
  "status": "OK",
  "data": ["login.can", "can_create_projects"],
  "user_id": "12345",
  "expired": 0
}

Error

  • status string required

    • “ERROR”

  • error string required

    Descriptive error message.

Response example
{
  "status": "ERROR",
  "error": "user not found"
}

Schema Types

The type parameter controls the format of the returned schema.

  • "tree"

    Permissions and data in a hierarchical structure. Includes secret_data and expiration times. Does not include project-specific access roles.

    Example
    {
  "status": "OK",
  "data": {
    "login": {
      "can": {"expired": 0, "value": true},
      "cannot": {"expired": 0, "value": false}
    },
    "private_data": {
      "can_create_apps": true,
      "can_create_projects": true
    },
    "public_data": {},
    "roles": [],
    "secret_data": {
      "application": {
        "canCreateJwt": {"value": true}
      }
    }
  },
  "user_id": "...",
  "expired": 1700000000
}

  • "list"

    Flat array of permissions as dot-separated paths. Includes merged role-based permissions. Excludes expired and secret_data permissions.

    Example
    {
  "status": "OK",
  "data": [
    "login.can",
    "private_data.can_create_projects",
    "private_data.can_create_apps",
    "private_data.projectAccess.openid.applications.50096.private_data.app.can_manage_app_api_keys",
    "private_data.projectAccess.openid.private_data.project.can_manage_services",
    "private_data.projectAccess.warthunder.private_data.project.can_grant_project_admins"
  ],
  "user_id": "...",
  "expired": 1700000000
}

  • "list_short"

    Flat list without visibility scope prefixes (public_data, private_data). Project-specific rules use a projectID/rule format (where projectID matches project_id). Excludes secret_data.

    Example
    {
  "status": "OK",
  "data": [
    "login.can|param0,paramN",
    "can_create_projects",
    "can_create_apps",
    "openid/applications/50096/app.can_manage_app_api_keys",
    "openid/services/50096/srv.can_manage_service_users",
    "openid/project.can_manage_services",
    "warthunder/project.can_grant_project_admins"
  ],
  "user_id": "...",
  "expired": 1700000000
}

  • "list_short" with with_apps_data

    When with_apps_data is true, the response data field includes rules, projects, and apps.

    Example
    {
  "status": "OK",
  "data": {
    "apps": {
      "openid": [{"id": 50096, "name": "OpenID"}],
      "warthunder": [{"id": 2, "name": "Warthunder Site"}]
    },
    "projects": {
      "openid": {"name": "OpenID clients"},
      "warthunder": {
        "aliases": ["warthunder_pc", "warthunder_mobile"],
        "name": "Warthunder"
      }
    },
    "rules": [
      "login.can|param0,paramN",
      "can_create_projects",
      "openid/project.can_manage_services",
      "warthunder/project.can_grant_project_admins"
    ]
  },
  "user_id": "...",
  "expired": 1700000000
}

  • "list" with with_exp

    When with_exp is true, the TTL in seconds is appended to each permission after a colon. 0 means no expiration.

    Example
    {
  "status": "OK",
  "data": [
    "login.can|param0,paramN:0",
    "can_create_projects:0",
    "openid/applications/50096/app.can_manage_app_api_keys:3600",
    "openid/project.can_manage_services:3600",
    "warthunder/project.can_grant_project_admins:3600"
  ],
  "user_id": "...",
  "expired": 1700000000
}

  • "list" with with_roles

    When with_roles is true, the response data field includes rules and roles.

    Example
    {
  "status": "OK",
  "data": {
    "rules": [
      "login.can|param0,paramN",
      "can_create_projects",
      "openid/project.can_manage_services",
      "warthunder/project.can_grant_project_admins"
    ],
    "roles": [
      "default",
      "openid.applications.50096/app_developer",
      "openid/administrator",
      "warthunder/owner"
    ]
  },
  "expired": 1700000000
}

  • "roles"

    Returns only the list of roles assigned to the user. Can be retrieved without a user JWT by providing a service JWT or service hash.

    Example
    {
  "status": "OK",
  "data": [
    "default",
    "openid.applications.50096/app_developer",
    "openid.services.50096/service_administrator",
    "openid/administrator",
    "warthunder/owner"
  ],
  "expired": 1700000000
}

Expiration and TTL for Roles

expired integer optional

Unix timestamp when the role expires. If the current time exceeds this value, the role is excluded from the effective permissions.

ttl integer optional

Number of seconds for which the role is valid from the moment the permissions list is generated. Takes precedence over expired if both are set.

If any role has a non-zero expired or ttl, the response expired field contains the earliest calculated expiration time. If neither is set, the response expired field is 0 (no time limit).

Edit User Schema

Additional Parameters for Permissions

For the "save" action, additional parameters can be specified in the params field of any permission. Parameters are listed as a comma-separated string.

"canManageTags": {"value": true, "params": "internal,game"}

Assign Roles

Roles can be assigned as an array of role name strings, or as objects with name, expired, and ttl fields.

"roles": [
  "writer",
  {"name": "reader", "expired": 0, "ttl": 0}
]

Resource-Specific Roles

For schemas with multiple resources sharing the same permission set, define general roles and assign them per resource in the user’s project access record, rather than creating a separate role for each resource.

For example, instead of creating separate warthunder_reader and crossout_reader roles, define a single reader role and assign it to the user per project:

Role definition:

{"data": {"meta": {"canRead": {"expired": 0, "ttl": 0, "value": true}}}, "name": "reader"}

The user’s project access record then maps this role to specific projects, applications, or services. The same reader role can be reused across any number of resources without duplicating the role definition.