Get identity

Read the authenticated caller and every account they can act under.

On this page

Request
Response
Top level
User object
Account object
Permission settings object
Every permission key
Errors

me returns who the current OAuth token belongs to and which accounts they can bill work to. Call it to confirm a token works, and to discover the account IDs you send in the account selection on account-scoped requests.

GEThttps://api2.rundiffusion.com/api/v2/me

AcceptsOAuth device flowPersonal API Access TokenCompany API Access Token

Request

Headers

AuthorizationstringRequired: Bearer token. This endpoint accepts an OAuth device flow token, a Personal API Access Token, or a Company API Access Token. See Authentication.Authorization: Bearer eyJhbGciOi…
X-Device-Idstringoptional: The connected-device ID, if your integration registered one. Sending it refreshes that device's last-used timestamp. Purely a hint: an unknown or malformed value never fails the request.X-Device-Id: b1f7c3d2-…

No query parameters and no body.

curl https://api2.rundiffusion.com/api/v2/me \
  -H "Authorization: Bearer $RUNDIFFUSION_TOKEN"

const me = await fetch('https://api2.rundiffusion.com/api/v2/me', {
  headers: { Authorization: `Bearer ${process.env.RUNDIFFUSION_TOKEN}` },
}).then(r => r.json());

me = requests.get(
    "https://api2.rundiffusion.com/api/v2/me",
    headers={"Authorization": f"Bearer {os.environ['RUNDIFFUSION_TOKEN']}"},
).json()

Response

200 OK with the caller and their accounts.

json

{
  "user": {
    "uid": "k3PqV9…",
    "email": "sam@example.com",
    "email_verified": true,
    "sign_in_provider": "google.com",
    "created_at": "2025-11-03T16:42:08+00:00",
    "top_up": { "available": true, "tokens": 500 }
  },
  "accounts": [
    {
      "id": "personal",
      "kind": "PERSONAL",
      "label": "Personal account",
      "permissions": {
        "GENERATE": true,
        "BATCH_GENERATION": true,
        "TOKEN_LIMIT": false,
        "TOKEN_COOLDOWN": false,
        "VIEW_TRAIN": true,
        "SHARE_ASSETS": true,
        "MANAGE_ALL_GENERATIONS": false,
        "NUM_RESULTS_LIMIT": false,
        "BLOCK_TOOLS": false,
        "OPEN_SOURCE_APPS_ADMIN": true,
        "USE_OPEN_SOURCE_APPS": true,
        "MANAGE_TEAM_MEMBERS": false,
        "SHOW_TOKEN_BALANCE": true,
        "USE_PLUGINS": true
      },
      "permission_settings": {
        "token_limit_settings": null,
        "token_cooldown_settings": null,
        "num_results_limit_settings": null,
        "restrict_tools_settings": null
      },
      "plugin_kinds": ["*", "miro", "photoshop", "revit"]
    },
    {
      "id": "Tq8vNc…",
      "kind": "TEAM",
      "label": "Design",
      "company_name": "Acme",
      "team_label": "Team",
      "permissions": {
        "GENERATE": true,
        "BATCH_GENERATION": true,
        "TOKEN_LIMIT": true,
        "TOKEN_COOLDOWN": false,
        "VIEW_TRAIN": true,
        "SHARE_ASSETS": true,
        "MANAGE_ALL_GENERATIONS": false,
        "NUM_RESULTS_LIMIT": false,
        "BLOCK_TOOLS": false,
        "OPEN_SOURCE_APPS_ADMIN": false,
        "USE_OPEN_SOURCE_APPS": true,
        "MANAGE_TEAM_MEMBERS": false,
        "SHOW_TOKEN_BALANCE": true,
        "USE_PLUGINS": true
      },
      "permission_settings": {
        "token_limit_settings": { "max": 50, "apply_to_total_run": true },
        "token_cooldown_settings": null,
        "num_results_limit_settings": null,
        "restrict_tools_settings": null
      },
      "plugin_kinds": ["*", "miro", "photoshop", "revit"]
    }
  ],
  "newly_joined_teams": []
}

Account IDs are the literal string personal for the caller's individual account, and a 20-character ID for a team.

Top level

userobject: The authenticated caller. See User object below.
accountsarray: Every account the caller can act under, personal first. An entry tells you what to send: a team's id goes in the team_id parameter, and the personal account is selected by sending no team_id at all. Never empty: a caller always has at least a personal account.
newly_joined_teamsarray: Teams the caller became a member of while this request was served, as a pending invitation is accepted on sign-in. Each entry is { team_id, team_name }, and team_name is null on a team with no name. Almost always empty: it reports what changed on this call, not the teams you belong to, which is accounts. They are already in accounts by the time you read this.

User object

uidstring: The caller's user ID, a 20-character opaque string. Example: k3PqV9….
emailstring: Email on the account. Example: sam@example.com.
email_verifiedboolean: Whether that email has been verified.
sign_in_providerstring | null: How the caller signed in. Example: google.com, or password for email and password.
createdstring (ISO 8601): When it was created, in UTC.
top_upobject: One-time token top-up availability, as { available, tokens }. Reads { "available": false, "tokens": 0 } on plans without the add-on.

Account object

idstring: The account's id: the literal string personal for the caller's individual account, or a 20-character team ID to send as team_id. Example: Tq8vNc….
kindstring: Which sort of account this is. Exactly one entry is PERSONAL.
labelstring: Display name for the account. Example: Design.
company_namestring: The company the team belongs to. Present on TEAM entries only. Example: Acme.
team_labelstring: The team's own label within that company. Present on TEAM entries only. Example: Team.
permissionsobject: One boolean per SCREAMING_SNAKE permission key, mirroring what the account may do. Resolved by the server for every account kind, including PERSONAL, which gets the plan defaults, so a client never needs its own idea of what a solo user may do.
permission_settingsobject: Parameters for whichever restriction permissions are active. All four keys are always present; each is null unless its permission is true in permissions. See the sections below for each shape.
plugin_kindsarray: Which plugin surfaces this account may use, already resolved against USE_PLUGINS. The * wildcard means every surface, including ones released later. Empty when USE_PLUGINS is false. Example: ["*", "miro", "photoshop", "revit"].

Permission settings object

Four keys, one per restriction that carries parameters. Every key is present on every account, and each is null unless two things are true: the matching permission is true, and the role has parameters stored for it.

token_limit_settingsobject | null: Parameters for TOKEN_LIMIT. See Token limit settings.
token_cooldown_settingsobject | null: Parameters for TOKEN_COOLDOWN. See Token cooldown settings.
num_results_limit_settingsobject | null: Parameters for NUM_RESULTS_LIMIT. See Num results limit settings.
restrict_tools_settingsobject | null: Parameters for BLOCK_TOOLS. See Restrict tools settings.

Token limit settings

Caps what a single generation may cost.

maxinteger | null: The ceiling, in whole tokens. A generation costing more than this is refused. Null when the role saved no ceiling, which means no limit.
apply_to_total_runboolean: When true the ceiling applies to the whole run, so cost times the number of results. When false it applies per generation.

json

{ "max": 50, "apply_to_total_run": true }

Token cooldown settings

Caps how much the account may spend within a rolling window.

tokensinteger | null: The spend threshold for the window, in whole tokens. Null when the role saved no threshold, which means no limit.
time_bucketstring | null: The window the threshold is measured over. Null when the role saved no window.

json

{ "tokens": 1000, "time_bucket": "1hr" }

Num results limit settings

maxinteger | null: The largest num_results this account may request on a generation. Null when the role saved no cap, which means no limit.

json

{ "max": 4 }

Restrict tools settings

Which tools this account may not run. A tool is blocked when its ID is listed, or when it carries a listed tool tag.

tool_tagsobject: Blocked tool tag IDs, as a map of ID to true. Match these against a tool's tool_tags array. Empty when nothing is blocked by tag. Example: { "Tg7mQx…": true }.
tool_idsarray: Tools blocked outright by ID, whatever their tags. Empty when none are. Example: ["Tl9xBv…"].

json

{
  "tool_tags": { "Tg7mQx…": true },
  "tool_ids": ["Tl9xBv…"]
}

Every permission key

The complete set. The middle column is the wording an admin sees for that key on the Team Roles page, so a support conversation about "Can generate" and your code's GENERATE are talking about the same switch.

Key	Shown in Team Roles as	Section	`true` means
`GENERATE`	Can generate	Generation Tools	May generate.
`BATCH_GENERATION`	Can use batch generation	Generation Tools	May run batch generations.
`VIEW_TRAIN`	Can train models	Generation Tools	May train models.
`SHARE_ASSETS`	Can manage Shared assets	Generation Tools	May change access settings on assets, including moving Private to Shared.
`MANAGE_ALL_GENERATIONS`	Can manage everyone's generations and boards	Generation Tools	May view, edit, and delete anyone's work on the team, Private included.
`USE_PLUGINS`	Allow plugin and API access	Generation Tools	May reach the API and the plugin surfaces listed in `plugin_kinds`.
`TOKEN_LIMIT`	Limit per generation token cost	Generation Tools	Restricted. A per-generation cap applies; read `token_limit_settings`.
`NUM_RESULTS_LIMIT`	Limit number of results per run	Generation Tools	Restricted. A cap on results per run applies; read `num_results_limit_settings`.
`BLOCK_TOOLS`	Block specific tools or an entire "Model Family"	Generation Tools	Restricted. Some tools are blocked; read `restrict_tools_settings`.
`TOKEN_COOLDOWN`	Implement a "Token Cooldown"	Team	Restricted. A spend-per-window cap applies; read `token_cooldown_settings`.
`SHOW_TOKEN_BALANCE`	Show Team token balance	Team	The team's token balance is visible to this member.
`MANAGE_TEAM_MEMBERS`	Can manage members	Team	May add and remove members.
`USE_OPEN_SOURCE_APPS`	Can use Open-Source Apps platform	Open-Source Apps	May use that platform.
`OPEN_SOURCE_APPS_ADMIN`	Can manage Open-Source Apps platform	Open-Source Apps	May administer that platform.

The word Team in Show Team token balance is whatever the company calls a team, and team_label on the account is that exact word. Substitute it to render what the admin sees: on a company that uses Studio the row reads Show Studio token balance.

Errors

401UNAUTHENTICATED: Missing, malformed, or expired token. This is the expected response when you call /me to test a credential that has gone stale, so it is a useful health check.
429RATE_LIMITED: Too many requests. Back off and retry per the Retry-After header. See Rate limits.

See Errors for the full envelope and the code list.

View as Markdown