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
URL Params
| Field | Type | Description |
|---|
| username | str | the username to login with |
HTTP statuses
| 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 |
Returns a Code object
| {
"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
URL Params
| Field | Type | Description |
|---|
| username | str | the username being logged in |
HTTP statuses
| 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 |
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.
GET /applications
HTTP statuses
| Status | Meaning |
|---|
| 200 OK | here's the list |
| 401 Unauthorized | this session is not logged in (click the lock above) |
Returns a list of PartialApplication objects
| [{
"client_id": 10392032,
"app_name": "Cool And Good App"
}, {
"client_id": 12938223,
"app_name": null
}] |
Get Application Endpoint
Get data about a specific application.
GET /applications/{client_id}
URL Params
| Field | Type | Description |
|---|
| client_id | int | the client ID of the application to get |
HTTP statuses
| 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 |
Returns an Application object
| {
"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.
PUT /applications
HTTP statuses
| 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) |
JSON Body Params
| 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) |
Returns an Application object
| {
"client_id": 17290129,
"client_secret": "ojfewpw...",
"app_name": "New Cool App",
"flags": 0,
"redirect_uris": []
} |
Update Application Endpoint
Update application data.
PATCH /applications/{client_id}
URL Params
| Field | Type | Description |
|---|
| client_id | int | the client ID of the application to update |
HTTP statuses
| 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 |
JSON Body Params
| 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 |
Returns an Application object
| {
"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.
DELETE /applications/{client_id}
URL Params
| Field | Type | Description |
|---|
| client_id | int | the client ID of the application to delete |
HTTP statuses
| 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.
HTTP statuses
| 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 |
JSON Body Params
| 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) |
Returns a Tokens object
| {
"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.
HTTP statuses
| 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 |
JSON Body Params
| 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 |
Returns a Tokens object
| {
"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.
GET /user
HTTP statuses
| 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) |
Returns an User object
| {
"user_id": 10114764,
"user_name": "kenny2scratch"
} |
Object Reference
Application Object
An application.
Application Structure
| 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.
PartialApplication Structure
| Field | Type | Description |
|---|
| client_id | int | the client ID |
| app_name | str? | the app name |
Code Object
Data used for API Scratch login.
Code Structure
| 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.
Tokens Structure
| 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.
User Structure
| Field | Type | Description |
|---|
| user_id | int | Scratch user ID |
| user_name | str | Scratch username (non-authoritative if 203) |
AppFlags
Application flags
| 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
Authorization Scopes
| Name |
Description
|
identify |
Grants permission to learn the Scratch username and user ID represented by this access token
|
