Document API authentication and apps API
This commit is contained in:
parent
9a13d804c5
commit
cd4ae5b7f5
33
docs/API.md
33
docs/API.md
@ -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>
|
||||
|
@ -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:
|
||||
|
Loading…
Reference in New Issue
Block a user