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
Two roles, two maps
Every company permission key
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": "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_id": "Cm4pQ7…",
      "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
      },
      "company_permissions": {
        "VIEW_COMPANY_REPORTS": false,
        "MANAGE_COMPANY": false,
        "MANAGE_TEAMS": true,
        "MANAGE_COMPANY_TEAM_ROLES": false,
        "MANAGE_API_TOKENS": false
      },
      "permission_settings": {
        "token_limit_settings": {
          "max": 50,
          "apply_to_total_run": true,
          "media_tool_tag_maxes": { "Tg7mQx…": 3000 }
        },
        "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_idstring: The id of the company the team belongs to. Present on TEAM entries only. Send it as company_id to the company-scoped endpoints, such as List teams. Example: Cm4pQ7….
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 INSIDE it. Comes from the caller's team role. 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.
company_permissionsobject: What the caller may do TO the organization that owns this team, such as reading its teams or its reports. Comes from the caller's company role, which is a different role from the one behind permissions. Present on TEAM entries only, since a personal account belongs to no company. Every key is always present, and every one defaults to false.
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. A role may set one ceiling for everything, or raise or lower it for particular media types: video typically costs several times what an image does, so one number rarely suits both.

maxinteger | null: The ceiling, in whole tokens, for any tool that media_tool_tag_maxes does not name. 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. It is not overridable per media type, because it decides how the ceiling is measured rather than how large it is.
media_tool_tag_maxesobject: Ceilings for specific media types, in whole tokens, keyed by the tool tag ID of a MEDIA tag. A tool carrying one of these tags is capped by that value instead of max. Empty when the role sets one ceiling for everything, which is the common case. Example: { "Tg7mQx…": 3000 }.

json

{
  "max": 50,
  "apply_to_total_run": true,
  "media_tool_tag_maxes": { "Tg7mQx…": 3000 }
}

To find the ceiling for a tool, look up each of its tool_tags IDs in media_tool_tag_maxes and use the value you find; if none match, use max. The keys are tool tag IDs of type MEDIA, the same IDs a tool carries in tool_tags and that List tool tags resolves to labels such as Image, Video, and 3D.

A tool carries at most one MEDIA tag today. If one ever carries two that are both listed, the lower ceiling applies, which is what the server enforces.

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…"]
}

Two roles, two maps

A member holds two independent roles, and each account carries the resolved map for one of them.

	`permissions`	`company_permissions`
Granted by	The member's team role	The member's company role
Edited on	The Team Roles page	The Company Roles page
Answers	What may I do inside this account?	What may I do to the organization?
Present on	Every account, `PERSONAL` included	`TEAM` entries only
Defaults to	The plan defaults	Every key `false`

They are separate maps because they are separate grants. A member can hold every key in permissions and none in company_permissions: running generations on a team says nothing about whether you may enumerate the company's teams or read its billing reports. Checking the wrong map is the usual reason a call that "should" work returns 403.

If you are looking up why a request was refused, match on the map the endpoint names. List teams and Get a team want MANAGE_TEAMS, and Token usage wants VIEW_COMPANY_REPORTS; both live in company_permissions. Everything under Library and Boards reads permissions.

Every company permission key

Five keys, always all present. The middle column is the wording an admin sees on the Company Roles page.

Key	Shown in Company Roles as	`true` means
`MANAGE_COMPANY`	Can manage company	May change company-wide settings.
`MANAGE_TEAMS`	Can manage teams and members	May read and administer every team in the company. Required by List teams and Get a team.
`MANAGE_COMPANY_TEAM_ROLES`	Can manage team roles	May edit the role definitions the `permissions` map above resolves from.
`MANAGE_API_TOKENS`	Can manage API tokens	May mint a Company API Access Token, including one that acts as another member.
`VIEW_COMPANY_REPORTS`	Can view company reports	May read company-wide usage. Required by Token usage.

Every one of these defaults to false. Unlike the team map, no plan grants any of them: a company role has to say yes. The word teams in Can manage teams and members follows team_label, the same way it does below.

Every permission key

The complete set of the team map. 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, which may differ by media type; 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