4.9 KiB
| title |
|---|
| meta.sr.ht API reference |
meta.sr.ht user API
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
}
- use_pgp_key is the ID of the user's preferred PGP key, which can be
found via
GET /api/user/pgp-keys/: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: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
- 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: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
}