The meta.sr.ht API allows you to view and edit user information on meta.sr.ht programmatically. This API follows the standard sourcehut API conventions.

Authentication

Authentication is done via the meta.sr.ht OAuth flow. The following OAuth scopes are available for meta.sr.ht:

  • audit:read: read the security audit log
  • keys:read, keys:write: read & update user SSH & PGP keys
  • profile:read, profile:write: read & update profile information
Resources
User resource

meta.sr.ht expands on the standard user resource.

{
  "canonical_name": "~username",
  "name": "username",
  "email": "email",
  "url": "url" or null,
  "location": "location" or null,
  "bio": "bio" or null,
  "use_pgp_key": pgp key resource ID
}
Audit log entry resource
{
  "id": integer,
  "ip": "IP address",
  "action": "event type",
  "details": "event details",
  "created": "timestamp"
}
SSH key resource
{
  "id": integer,
  "authorized": "timestamp",
  "comment": "SSH key comment",
  "fingerprint": "SSH key fingerprint",
  "key": "SSH key (authorized_keys format)",
  "owner": short-form user resource,
  "last_used": "timestamp"
}
  • last_used is omitted when viewing an SSH key which is not owned by the authorized user.
PGP key resource
{
  "id": integer,
  "key": "armored PGP key",
  "key_id": "PGP key fingerprint",
  "email": "First email found in the PGP key",
  "authorized": "timestamp",
  "owner": short-form user resource
}
Endpoints
GET /api/user/profile

Returns the authenticated user's user resource.

OAuth scope: profile:read

PUT /api/user/profile

Updates the authenticated user's profile.

OAuth scope: profile:write

Request body

{
  "url": "url" or null, (optional)
  "location": "location" or null, (optional)
  "bio": "bio" or null, (optional)
  "email": "email" (optional)
}

Response

Updated user resource.

Notes

  • When updating email, the returned user resource will not reflect the update. The user must click the confirmation link which is sent to their new email address before the update will take effect.
GET /api/user/audit-log

List of audit log entry resources.

OAuth scope: audit-log:read

GET /api/user/ssh-keys

List of SSH key resources.

OAuth scope: keys:read

POST /api/user/ssh-keys

Creates a new SSH key resource.

OAuth scope: keys:write

Request body

{
  "ssh-key": "SSH key (authorized_keys format)"
}

Response

The new SSH key resource.

GET /api/user/ssh-keys/:id

Retrieves an SSH key resource.

OAuth scope: keys:read

PUT /api/user/ssh-keys/:id

Updates the "last_used" time of this SSH key resource.

OAuth scope: keys:read

Response

The updated SSH key resource.

DELETE /api/user/ssh-keys/:id

Deletes this SSH key resource.

OAuth scope: keys:write

GET /api/user/pgp-keys

List of PGP key resources.

OAuth scope: keys:read

POST /api/user/pgp-keys

Creates a new PGP key resource.

OAuth scope: keys:write

Request body

{
  "pgp-key": "armored PGP key"
}

Response

The new PGP key resource.

GET /api/user/pgp-keys/:id

Retrieves a PGP key resource.

OAuth scope: keys:read

DELETE /api/user/pgp-keys/:id

Deletes this PGP key resource.

OAuth scope: keys:write

Webhooks
/api/user/...

Webhook for user events. Includes the standard webhook endpoints

profile:update

Issued when the user's profile (bio, email, etc) is updated.

OAuth scope: profile:read

Request body

The updated user resource.

ssh-key:add

Issued when the user adds an SSH key to their account.

OAuth scope: keys:read

Request body

The new SSH key resource.

ssh-key:remove

Issued when the user removes an SSH key from their account.

OAuth scope: keys:read

Request body

{
  "id": integer ID of the affected SSH key resource
}
pgp-key:add

Issued when the user adds a PGP key to their account.

OAuth scope: keys:read

Request body

The new PGP key resource.

pgp-key:remove

Issued when the user removes a PGP key from their account.

OAuth scope: keys:read

Request body

{
  "id": integer ID of the affected PGP key resource
}

About this wiki

commit a290ce243e74f89fc35cd4e3467a580edbc35399
Author: Drew DeVault <sir@cmpwn.com>
Date:   2024-05-27T14:24:11+02:00

license.md: add link to joinup chooser
Clone this wiki
https://git.sr.ht/~sircmpwn/sr.ht-docs (read-only)
git@git.sr.ht:~sircmpwn/sr.ht-docs (read/write)