From ScratchOAuth2
m (Kenny2scratch moved page SOA2:API Reference to API Reference without leaving a redirect) |
m (more specific /user 404) |
||
(One intermediate revision by the same user not shown) | |||
Line 227: | Line 227: | ||
|401=missing/incorrect authorization (click the lock above) | |401=missing/incorrect authorization (click the lock above) | ||
|403=invalid scopes for this access token | |403=invalid scopes for this access token | ||
− | |404=we | + | |404=we are missing their non-lowercased username (this shouldn't ever be possible, but is documented for completeness) |
|returns=User | |returns=User | ||
|example= | |example= | ||
Line 244: | Line 244: | ||
{{param|client_id|int|the client ID}} | {{param|client_id|int|the client ID}} | ||
{{param|client_secret|str|the client secret}} | {{param|client_secret|str|the client secret}} | ||
+ | {{param|created_at|int|Unix timestamp when this application was created}} | ||
{{param|app_name|str?|the app name - can be <code>null</code>, in which case authorization will display <nowiki>[unnamed application]</nowiki> as the app name}} | {{param|app_name|str?|the app name - can be <code>null</code>, in which case authorization will display <nowiki>[unnamed application]</nowiki> as the app name}} | ||
{{param|flags|int|[[#AppFlags|application flags]], bitwise ORed together}} | {{param|flags|int|[[#AppFlags|application flags]], bitwise ORed together}} |
Latest revision as of 19:58, 23 November 2021
API Base URL
https://oauth2.scratch-wiki.info/w/rest.php/soa2/v0
Authorization
Scratch
Client registration endpoints require the session itself (tracked by cookies - make sure they are passed) to be logged in with Scratch. Since it is probably difficult to use the UI to login and then pass off the session to code somehow (unless using browser JavaScript), this is best done with the #Scratch Login Endpoints:
- Start the login
- Personally comment the provided
code
on your Scratch profile - Finish the login, providing the CSRF token given in step 1
- This session is now logged in
Token
Scoped endpoints require an access token for authorization. This must be passed in a header. Example:
GET <api-root>/user HTTP/1.1
...
Authorization: Bearer <base64-encoded access token>
...
Scratch Login Endpoints
Start Login Endpoint
Start logging in via the API
/login/{username}
Field | Type | Description |
---|---|---|
username | str | the username to login with |
Status | Meaning |
---|---|
200 OK | information to complete the login |
400 Bad Request | username invalid by Scratch standards |
404 Not Found | username 404ed on Scratch API |
{ "username": "NameSniped", "csrf": "74d3340ff3d152a13c799c257f255601602800a8+\\", "code": "4b8de:ac2dc:7b20f:bde85:e2fc0:8c91d:78408:44f60:b49f8:8fd4c:fd9ac:c027c:e00f" } |
Finish Login Endpoint
Finish logging in via the API
/login/{username}
Field | Type | Description |
---|---|---|
username | str | the username being logged in |
Status | Meaning |
---|---|
204 No Content | login success |
400 Bad Request | username invalid by Scratch standards or request body was malformed |
403 Forbidden | comment not found on profile or CSRF tokens didn't match |
Field | Type | Description |
---|---|---|
csrf | str | the CSRF token provided by PUT /login/{username} |
Application Registration Endpoints
If using Special:SOA2Apps is unacceptable for some reason, you can use these endpoints instead.
Get Partial Applications Endpoint
List all applications owned by this user.
Status | Meaning |
---|---|
200 OK | here's the list |
401 Unauthorized | this session is not logged in (click the lock above) |
[{ "client_id": 10392032, "app_name": "Cool And Good App" }, { "client_id": 12938223, "app_name": null }] |
Get Application Endpoint
Get data about a specific application.
Field | Type | Description |
---|---|---|
client_id | int | the client ID of the application to get |
Status | Meaning |
---|---|
200 OK | here's the info |
401 Unauthorized | this session is not logged in (click the lock above) |
404 Not Found | no such client ID belonging to you, valid or not |
{ "client_id": 10392032, "client_secret": "aospf...", "app_name": "Cool And Good App", "flags": 1, "redirect_uris": ["https://...", "https://..."] } |
Create Application Endpoint
Create a new application.
Status | Meaning |
---|---|
200 OK | new application's info |
400 Bad Request | request body was malformed |
401 Unauthorized | this session is not logged in (click the lock above) |
Field | Type | Description |
---|---|---|
app_name | str? | name of the app, or null for no name |
redirect_uris | str[]? | list of URIs to redirect to after auth completion, or null /an empty list to redirect to a builtin page to display the code for copying (empty URIs are silently dropped) |
{ "client_id": 17290129, "client_secret": "ojfewpw...", "app_name": "New Cool App", "flags": 0, "redirect_uris": [] } |
Update Application Endpoint
Update application data.
Field | Type | Description |
---|---|---|
client_id | int | the client ID of the application to update |
Status | Meaning |
---|---|
200 OK | Application after update |
400 Bad Request | request body was malformed |
401 Unauthorized | this session is not logged in (click the lock above) |
404 Not Found | no such client ID belonging to you, valid or not |
Field | Type | Description |
---|---|---|
reset_secret | ?bool | setting true will reset the app secret |
app_name | ?str? | new name for the app (can be null to unset name) |
redirect_uris | ?str[]? | list of redirect URIs to replace the original list |
{ "client_id": 17290129, "client_secret": "kdjofw...", "app_name": "Not So New Cool App", "flags": 0, "redirect_uris": ["https://these.will/be", "https://overwritten.not/appended"] } |
Deregister Application Endpoint
Remove an application from use.
Field | Type | Description |
---|---|---|
client_id | int | the client ID of the application to delete |
Status | Meaning |
---|---|
204 No Content | it is done |
401 Unauthorized | this session is not logged in (click the lock above) |
404 Not Found | no such client ID belonging to you, valid or not |
Authorization Endpoints
For doing The Actual Thing!
Request Refresh Token Endpoint
Request an access and refresh token together.
/tokens
Status | Meaning |
---|---|
200 OK | token information |
400 Bad Request | request body was malformed |
401 Unauthorized | client ID/secret combo is not valid |
404 Not Found | invalid token-getter code |
417 Expectation Failed | scopes passed in body did not match scopes that user allowed |
Field | Type | Description |
---|---|---|
client_id | int | client ID of the app requesting these tokens |
client_secret | str | client secret of said app |
code | str | token-getter code passed to the redirect URI after successful authorization |
scopes | str|str[] | scopes client is requesting, to confirm that the user gave the right ones (space-separated or array) |
{ "access_token": "idoewjW...", "access_expiry": 1605987220, "refresh_token": "diFWOd...", "refresh_expiry": 1705987220, "scopes": ["identify"] } |
Request Access Token Endpoint
Request a new access token using a refresh token.
/tokens
Status | Meaning |
---|---|
200 OK | new token information |
400 Bad Request | request body was malformed |
401 Unauthorized | client ID/secret combo is not valid |
404 Not Found | no such refresh token |
410 Gone | refresh token is expired |
Field | Type | Description |
---|---|---|
client_id | int | client ID of the app requesting this token |
client_secret | str | client secret of said app |
refresh_token | str | refresh token already granted |
{ "access_token": "idoewjW...", "access_expiry": 1605987220, "refresh_token": "diFWOd...", "refresh_expiry": 1705987220, "scopes": ["identify"] } |
Scoped Endpoints
Request Username Endpoint
Get the username of the Scratch user this access token represents.
Status | Meaning |
---|---|
200 OK | the username |
203 Non-Authoritative Information | we stored their username, but the comments API 404ed so they could be banned or deleted or renamed |
401 Unauthorized | missing/incorrect authorization (click the lock above) |
403 Forbidden | invalid scopes for this access token |
404 Not Found | we are missing their non-lowercased username (this shouldn't ever be possible, but is documented for completeness) |
{ "user_id": 10114764, "user_name": "kenny2scratch" } |
Object Reference
Application Object
An application.
Field | Type | Description |
---|---|---|
client_id | int | the client ID |
client_secret | str | the client secret |
created_at | int | Unix timestamp when this application was created |
app_name | str? | the app name - can be null , in which case authorization will display [unnamed application] as the app name |
flags | int | application flags, bitwise ORed together |
redirect_uris | str[] | a list of redirect URIs (which can be empty) |
PartialApplication Object
A partial application object.
Field | Type | Description |
---|---|---|
client_id | int | the client ID |
app_name | str? | the app name |
Code Object
Data used for API Scratch login.
Field | Type | Description |
---|---|---|
username | str | the username being logged in |
csrf | str | a CSRF token |
code | str | the code to comment on the profile |
Tokens Object
Token data from an authorization endpoint.
Field | Type | Description |
---|---|---|
access_token | str | the user access token |
access_expiry | int | Unix timestamp when access token expires |
refresh_token | str | the refresh token |
refresh_expiry | int | Unix timestamp when refresh token expires |
scopes | str[] | array of scopes granted to this token pair |
User Object
Username data for a Scratch user.
Field | Type | Description |
---|---|---|
user_id | int | Scratch user ID |
user_name | str | Scratch username (non-authoritative if 203) |
AppFlags
Name | Value | Description |
---|---|---|
NAME_APPROVED | 1 << 0 | Whether the app's name has been moderated and vetted. Authorization will display [application name unmoderated] until it has, unless the name is null . |
VERIFIED | 1 << 1 | Apps with this flag will have a superscript checkmark to distinguish them from potential impostors. |
HIDE_OWNER | 1 << 2 | By default, authorization displays the Scratch username of the owner of the app. If this flag is set, it will not. |
Scopes
Name | Description |
---|---|
identify |
Grants permission to learn the Scratch username and user ID represented by this access token |