aboutsummaryrefslogblamecommitdiffstats
path: root/meta.sr.ht/user-api.md
blob: dab8838af85fb41495a1ecb6ce20e14dcf52bab1 (plain) (tree)
1
2
3
4
5
6
7
8
9
10



                               

                                                                             
                                  


                 

                                                                         









                                                                        
                                             












                                    

                                                                           














































                                                                            

                                                                 
                               
 
                         


                                         
                                
 






















                                                                              

                                                               
                                 
 
                          


                                               
                            
 
                           


                                                    

                             













                                               

                                                    
                            
 
                              


                                                      
                            
 





                                                  

                              
                             
 
                          


                                               
                            
 
                           


                                                    

                             













                                              

                                                  
                            
 
                                 


                              

                             




                                                       
                                        


                   

                                                            

                               





                                            

                                                      

                            





                                              

                                                           

                            









                                                   

                                                     

                            





                                              

                                                          

                            






                                                   
---
title: meta.sr.ht API reference
---

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

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

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

### PUT /api/user/profile

Updates the authenticated user's profile.

**OAuth scope**: `profile:write`

**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

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

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

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

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

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

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

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

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

**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

Retrieves an [SSH key resource](#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](#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](#pgp-key-resource).

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

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

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

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

**Request body**

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

**Response**

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

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

Retrieves a [PGP key resource](#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](/api-conventions.md#webhooks)

#### profile:update

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

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

**Request body**

The updated [user resource](#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-resource).

#### ssh-key:remove

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

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

**Request body**

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

#### pgp-key:remove

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

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

**Request body**

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