Skip to content

Identity API

Read and update the profile of the person who owns a credential, and manage their devices and notifications across workspaces.

Credentials

  • GET and PATCH /api/v1/me accept a personal API token or a workspace API key. A workspace key needs a Pro or Enterprise workspace, because profile:read and profile:write are not Free scopes.
  • /me/feed-preferences, /me/time-preferences, and DELETE /me/avatar also accept a workspace API key. They act on the key's owner in that workspace. A personal API token sends the X-Project-Feed-Workspace header.
  • Session tokens, sent with X-Project-Feed-Workspace, can read and change your profile, remove your photo, and read and change your account notification defaults and your feed and time tracking preferences. Viewers can too, because these are your own settings.
  • Session tokens can also manage email addresses, sessions, authenticator apps, and account deletion. Email addresses, sessions, security activity, and the deletion check also accept a personal API token. Step-up, authenticator apps, a new primary address, removing a verified address, and deleting the account need a session token.
  • Every other route here needs a personal API token. A workspace key gets 400, so it cannot list memberships, devices, or notifications outside its own workspace.
  • Personal tokens work on any plan, and a token that is not allowed into any workspace can still call these routes. Workspace access only limits which workspaces appear in notifications.

For one workspace's notifications and preferences, use the Notifications API.

Endpoints

Feed preferences

The activity feed shows what you can see in the app, minus the kinds you hide. These preferences are per workspace. The first change to a workspace copies your account defaults and saves them as that workspace's own setting. Send scope=account to read or change the account defaults instead. The preference names are: showPostPublished, showPostComments, showPostReviews, showPostEdits, showTaskMilestones, showTaskComments, showTaskFieldChanges, showTaskMicroChanges, showCanvasCreated, showDocsActivity, showTimeTracking, showProjectActivity, showMemberActivity, showIntegrationActivity, showIntegrationCommits, showIntegrationReviews, showIntegrationDeployments, showIntegrationIssues, showIntegrationDesign.

Your own activity counts and charts are on the Reports API.

Step-up

Changes that could lock someone out of their account need a fresh email code, not just a signed-in session: deleting the account, changing the primary address, removing a verified address, adding an authenticator app, and removing one. From an app session, removing a workspace admin or moving one to member or viewer, transferring ownership and deleting a workspace need one too.

  • POST /api/v1/me/step-up with the action, and the address, authenticator or user ID when there is one, emails a code.
  • POST /api/v1/me/step-up/:id/verify with the code returns a token.
  • Send the token in the X-Project-Feed-Step-Up header on the change. It works once, within 5 minutes, from the same session, for that action and target only.

Next steps

Image preview
100%