Document API authentication and apps API

This commit is contained in:
Baptiste Gelez 2018-10-22 15:22:53 +01:00
parent 9a13d804c5
commit cd4ae5b7f5
2 changed files with 52 additions and 0 deletions

View file

@ -1,3 +1,36 @@
# API documentation
## Getting an API token
To get access to the API, you should register your app and obtain a
token. To do so, use the `apps` API (accessible without a token) to create
a new app. Store the result somewhere for future use.
Then send a request to `/api/v1/oauth2`, with the following GET parameters:
- `client_id`, your client ID.
- `client_secret`, your client secret.
- `scopes`, the scopes you want to access. They are separated by `+`, and can either
be `read` (global read), `write` (global write), `read:SCOPE` (read only in `SCOPE`),
or `write:SCOPE` (write only in `SCOPE`).
- `username` the username (not the email, display name nor the fully qualified name) of the
user using your app.
- `password`, the password of the user.
Plume will respond with something similar to:
```json
{
"token": "<YOUR TOKEN HERE>"
}
```
To authenticate your requests you should put this token in the `Authorization` header:
```
Authorization: Bearer <YOUR TOKEN HERE>
```
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<div id="api"></div>

View file

@ -10,6 +10,10 @@ servers:
description: Demo instance
paths:
/apps:
post:
description:
Registers an application.
/posts/{id}:
get:
description:
@ -27,6 +31,21 @@ paths:
List posts.
definitions:
App:
type: "object"
properties:
name:
type: "string"
example: "My app"
website:
type: "string"
example: "https://my.app"
client_id:
type: "string"
example: "My app"
client_secret:
type: "string"
example: "My app"
Post:
type: "object"
properties: