forked from FoundKeyGang/FoundKey
43 lines
2.4 KiB
Markdown
43 lines
2.4 KiB
Markdown
|
# 3rd party access
|
||
|
|
Foundkey supports:
|
||
|
|
- OAuth 2.0 Authorization Code grant per RFC 6749.
|
||
|
|
- OAuth Bearer Token Usage per RFC 6750.
|
||
|
|
- Proof Key for Code Exchange (PKCE) per RFC 7636.
|
||
|
|
- OAuth 2.0 Authorization Server Metadata per RFC 8414.
|
||
|
|
|
||
|
|
# Discovery
|
||
|
|
Because the implementation may change in the future, it is recommended that you use OAuth 2.0 Authorization Server Metadata a.k.a. OpenID Connect Discovery.
|
||
|
|
In short, this means that to discover the URLs for the grant endpoints you should request `/.well-known/oauth-authorization-server`, which is a JSON object.
|
||
|
|
From there, `authorization_endpoint` and `token_endpoint` will probably be most interesting to you.
|
||
|
|
The definitions of all data fields are to be found in [RFC 8414, section 2](https://www.rfc-editor.org/rfc/rfc8414#section-2).
|
||
|
|
|
||
|
|
# App registration
|
||
|
|
Before using the OAuth grant you need to register your application.
|
||
|
|
Currently you will need to use the pre-existing Misskey API to register, though Dynamic Client Registration may be implemented at a later point.
|
||
|
|
(You'd be able to tell from the Authorization Server Metadata, see above.)
|
||
|
|
|
||
|
|
The data you will need to know before registering is the following:
|
||
|
|
- a name for your app,
|
||
|
|
- a short description to be shown to users,
|
||
|
|
- which API permissions you need, and
|
||
|
|
- the callback URL you want to use.
|
||
|
|
|
||
|
|
There can only be 1 callback URL per registration.
|
||
|
|
|
||
|
|
Note that you can specify permissions a 2nd time in the OAuth flow.
|
||
|
|
If you do not provide permissions again in the grant flow, the default is to use all permissions you gave when registering the app.
|
||
|
|
If you do provide permissions in the grant flow, permissions that were not registered will never be granted.
|
||
|
|
A list of available permissions can be viewed on any Foundkey instance by going to the API documentation at `/api-doc`.
|
||
|
|
|
||
|
|
To register your app you need to `POST` to `/api/app/create`.
|
||
|
|
The body of the request must be a JSON object with the following keys:
|
||
|
|
- `name` (string): a name for your app,
|
||
|
|
- `description` (string): a short description to be shown to users,
|
||
|
|
- `permission` (array of permission names) which API permissions you need, and
|
||
|
|
- `callbackUrl` (string): the callback URL you want to use.
|
||
|
|
|
||
|
|
If successful (HTTP response code 200) you will receive back a JSON object containing among other things:
|
||
|
|
- `id` (string): the client ID
|
||
|
|
- `secret` (string): the client secret
|
||
|
|
With these credentials you should be able to use the Authorization Code grant to obtain authorization.
|