path: root/meta.sr.ht/user-api.md

# 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](../api-conventions.md).

## Authentication

Authentication is done via the [meta.sr.ht OAuth
flow](oauth-api.md). 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](../api-conventions.md#user-resource).

```json
{
  "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`](#get-apiuserpgp-keysid).

### Audit log entry resource

```json
{
  "id": integer,
  "ip": "IP address",
  "action": "event type",
  "details": "event details",
  "created": "timestamp"
}
```

### SSH key resource

```json
{
  "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

```json
{
  "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

**OAuth scope**: `profile:read`

Returns the authenticated user's [user resource](#user-resource).

### PUT /api/user/profile

**OAuth scope**: `profile:update`

Updates the authenticated user's profile.

**Request body**

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

**Response**

Updated [user resource](#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

**OAuth scope**: `audit-log:read`

List of [audit log entry resources](#audit-log-entry-resource).

### GET /api/user/ssh-keys

**OAuth scope**: `keys:read`

List of [SSH key resources](#ssh-key-resource).

### POST /api/user/ssh-keys

**OAuth scope**: `keys:write`

Creates a new [SSH key resource](#ssh-key-resource).

**Request body**

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

**Response**

The new [SSH key resource](#ssh-key-resource).

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

**OAuth scope**: `keys:read`

Retrieves an [SSH key resource](#ssh-key-resource). 

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

**OAuth scope**: `keys:write`

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

**Response**

The updated [SSH key resource](#ssh-key-resource).

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

**OAuth scope**: `keys:write`

Deletes this SSH key resource.

### GET /api/user/pgp-keys

**OAuth scope**: `keys:read`

List of [PGP key resources](#pgp-key-resource).

### POST /api/user/pgp-keys

**OAuth scope**: `keys:write`

Creates a new [PGP key resource](#pgp-key-resource).

**Request body**

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

**Response**

The new [PGP key resource](#pgp-key-resource).

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

**OAuth scope**: `keys:read`

Retrieves a [PGP key resource](#pgp-key-resource).

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

**OAuth scope**: `keys:write`

Deletes this PGP key resource.

## Webhooks

### /api/user/...

Webhook for user events. Includes the [standard webhook
endpoints](../api-conventions.md#webhooks)

#### profile:update

**OAuth scope**: `profile:read`

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

**Request body**

The updated [user resource](#user-resource).

#### ssh-key:add

**OAuth scope**: `keys:read`

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

**Request body**

The new [SSH key resource](#ssh-key-resource).

#### ssh-key:remove

**OAuth scope**: `keys:read`

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

**Request body**

```json
{
  "id": integer ID of the affected SSH key resource
}
```

#### pgp-key:add

**OAuth scope**: `keys:read`

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

**Request body**

The new [PGP key resource](#pgp-key-resource).

#### pgp-key:remove

**OAuth scope**: `keys:read`

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

**Request body**

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