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:

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

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:update

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

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:write

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 c054289ccb61ea6faf3cd2a7fd410692f2da6fff
Author: Timothée Floure <timothee.floure@posteo.net>
Date:   2019-12-03T11:05:33+01:00

Update F31, add F32 to builds.sr.ht image compatibility page
Clone this wiki
https://git.sr.ht/~sircmpwn/sr.ht-docs (read-only)
git@git.sr.ht:~sircmpwn/sr.ht-docs (read/write)