Me

1 endpoint

Get me#

GET /me

Answers what the request's credential is: an API key or a session, its role, and the space (organization and mode) it acts in, after On-Behalf-Of. An SDK calls it to check its key (a test key in production, the wrong organization). A session also gets its user, the spaces it may switch to, and its re-authentication window while it lasts; a session without an organization gets those only (no role, no space). Any valid credential, from either app; none → 401.

Auth: X-API-Key: any key

On-Behalf-Of: Honored: acts in the member's space

Idempotency-Key: Ignored

Success: 200

Request

request.sh

curl https://api.qbitflow.app/v2/me \  -H "X-API-Key: $QBITFLOW_API_KEY"# 200: a Me

client-setup.ts

Source

// One client per API key, shared by the whole program. A blank key, one not starting with// sk_, or one with a space or a control character, throws a ValidationError (nothing is sent).const client = new QBitFlow(process.env.QBITFLOW_API_KEY ?? ''); // The recommended start-up check: what is this key, and which mode is it in? An// AuthenticationError for an unknown or revoked key.const me = await client.me();console.log(`${me.role} key, test mode: ${me.space?.test}`);

client_setup.py

Source

# One client per API key, shared by the whole program. ValidationError: not an sk_… key.client = qbitflow.QBitFlow(os.environ["QBITFLOW_API_KEY"]) # The recommended start-up check: what is this key, and which mode is it in?me = client.me()  # AuthenticationError for an unknown or revoked keyif me.space is not None:    print(f"{me.space.organization_name}, role {me.role}, test mode {me.space.test}")

client/main.go

Source

// One client per API key, shared by the whole program: it is safe for concurrent use.client, err := qbitflow.NewClient(os.Getenv("QBITFLOW_API_KEY"))if err != nil {	log.Fatal(err) // a *qbitflow.ValidationError: no key, or not an sk_… key} // The recommended start-up check: what is this key, and which mode is it in?me, err := client.Me(ctx)if err != nil {	log.Fatal(err) // a *qbitflow.AuthenticationError for an unknown or revoked key}if me.Space != nil {	fmt.Printf("%s, role %s, test mode %v\n", me.Space.OrganizationName, me.Role, me.Space.Test)}

client-setup.php

Source

// One client per API key, shared by the whole application.$client = new \QBitFlow\QBitFlow(apiKey: (string) getenv('QBITFLOW_API_KEY')); // The recommended start-up check: which space and mode is this key in?$me = $client->me(); // an AuthenticationException for an unknown or revoked keyprintf("%s, role %s, %s mode\n", $me->space?->organizationName ?? '?', $me->role ?? '?', $me->space?->test ? 'test' : 'live');

Response

A Me.

9 fields of Me

credentialstring
apiKey or session
One of:
- apiKeyAn API key (X-API-Key)
- sessionA signed-in person's access token (Authorization: Bearer, the dashboard or qbf.cash)
apiKeyUuidstringOptional
The key, for an API key (as GET /api-keys lists it)
userUuidstringOptional
Who signed in, for a session. Absent for an API key: a key acts for its space, not for the person who created it
rolestringOptional
What the request may do in the space: owner, admin, user (a member, or an owner or admin acting as one) or handle (qbf.cash). An API key is at most admin. Absent for a session without an organization
onBehalfOfUserUuidstringOptional
The member an organization key (On-Behalf-Of) or an owner or admin (the dashboard) acts as: the space is that member's. Absent otherwise
spaceEntryOptional
The space the request reads and writes in, as GET /account/spaces describes one (its test says the mode; member names the member of a personal space). Absent for a session without an organization (an account removed from its last one, or not in one yet): it creates one (POST /organization) or accepts an invitation
11 fields of Entry
- uuidstring
  Its only id (a UUIDv7)
- organizationUuidstring
  The organization
- userUuidstringOptional
  The member of a personal space; omitted for the shared space
- testboolean
- trustedAtstringOptional
  Absent (nil) while the organization holds this member's funds (held funds). Always set on a shared space
- createdAtstring
- organizationNamestring
  Name of the space's organization
- rolestring
  The user's role in the organization: owner, admin, user or handle
- memberMemberOptional
  The member whose space it is (its userUuid), named: who an owner or admin acting in it acts as. Absent for the organization's own space
  4 fields of Member
  userUuidstring
  The member (as GET /members lists them)
  firstNamestring
  lastNamestring
  Absent when the account has none
  emailstring
- organizationFeePercentnumberOptional
  The organization's fee on the member's payments in this space, in bps ("0": none). Written as organizationFeePercent. Absent for the organization's own space (it takes no fee from itself)
- staffViewboolean
  True on the entry of a staff view (QBitFlow staff reading the space from the console, read-only: docs/api routes/account.md § The staff view); false on every space of your own
userUserOptional
Who signed in, as GET /account answers
6 fields of User
- uuidstring
  Its only id (a UUIDv7)
- firstNamestring
  The person's first name
- lastNamestring
  Their last name
- emailstring
- createdAtstring
- updatedAtstring
spacesarray of Entry
Every space the account enters in this app, as GET /account/spaces lists them ([] without an organization, and for an API key)
11 fields of each Entry
- uuidstring
  Its only id (a UUIDv7)
- organizationUuidstring
  The organization
- userUuidstringOptional
  The member of a personal space; omitted for the shared space
- testboolean
- trustedAtstringOptional
  Absent (nil) while the organization holds this member's funds (held funds). Always set on a shared space
- createdAtstring
- organizationNamestring
  Name of the space's organization
- rolestring
  The user's role in the organization: owner, admin, user or handle
- memberMemberOptional
  The member whose space it is (its userUuid), named: who an owner or admin acting in it acts as. Absent for the organization's own space
  4 fields of Member
  userUuidstring
  The member (as GET /members lists them)
  firstNamestring
  lastNamestring
  Absent when the account has none
  emailstring
- organizationFeePercentnumberOptional
  The organization's fee on the member's payments in this space, in bps ("0": none). Written as organizationFeePercent. Absent for the organization's own space (it takes no fee from itself)
- staffViewboolean
  True on the entry of a staff view (QBitFlow staff reading the space from the console, read-only: docs/api routes/account.md § The staff view); false on every space of your own
reauthenticatedUntilstringOptional
While the session's re-authentication lasts: when it ends. Until then, the changes that need one (403 reauth_required) go through without asking again. Absent when there is none, or it ended

Errors

The common codes only, as any route (what each means):

Edge cases

The contract's rules for these routes: Authentication · The answer (Me).

Read all 2

Authentication

Any valid credential, from either app: an API key (organization's or member's, with or without On-Behalf-Of), a dashboard session, a qbf.cash session. None, or an invalid one → 401 unauthorized.

The answer (`Me`)

credential: apiKey or session.
An API key: apiKeyUuid is the key (as GET /api-keys lists it). No userUuid: a key acts for its space, not for the person who created it (GET /account still answers that person). spaces is [], and user and reauthenticatedUntil are absent.
A session: userUuid is who signed in, user the account (as GET /account answers it), spaces the spaces it may switch to (as GET /account/spaces lists them), and reauthenticatedUntil while its re-authentication lasts. No apiKeyUuid.
role is what the request may do in its space: owner or admin in the organization's space (an organization key is admin), user in a member's space (the member, or an owner, admin or organization key acting as them), handle for qbf.cash.
onBehalfOfUserUuid is the member acted as, when an organization key sends On-Behalf-Of or an owner or admin switched into a member's space; absent otherwise.
space is the request's space in the one shape every space has (Entry, as GET /account/spaces and Login.space write it): uuid, organizationUuid, organizationName, role (the caller's own role in the organization: an owner acting as a member stays owner here, while the top-level role is user), test (the mode: a test key answers true), createdAt, trustedAt (absent while the organization holds the member's funds), and for a member's space userUuid, organizationFeePercent (a string, "0" when none; absent on the organization's own space) and member. The space is the one every other route of the request reads and writes (spaces).
space.member names the member whose space it is: userUuid, firstName, lastName, email. It is there whoever reads it (the member, or the team acting as them: what an "acting as" banner shows, with no admin route to call). Absent in the organization's own space.
space.staffView (a boolean, always present) is false for every credential of your own, an API key always; true only with the token of a QBitFlow staff view (the staff console's read-only view of a merchant's space: Account and credential § The staff view), whose space is the viewed space (space.role owner; in a member's space the top-level role is user, with onBehalfOfUserUuid).
A session without an organization gets no role and no space.
Nothing is changed or recorded (an API key's lastUsedAt aside, as on any request).

The codes named here

401unauthorized
missing / invalid JWT or API key, an ended login

Get me#

Response

Errors

Edge cases

Authentication

The answer (Me)

The codes named here

The answer (`Me`)