From ScratchOAuth2

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:

  1. Start the login
  2. Personally comment the provided code on your Scratch profile
  3. Finish the login, providing the CSRF token given in step 1
  4. 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
FieldTypeDescription
usernamestrthe username to login with
HTTP statuses
StatusMeaning
200 OKinformation to complete the login
400 Bad Requestusername invalid by Scratch standards
404 Not Foundusername 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
FieldTypeDescription
usernamestrthe username being logged in
HTTP statuses
StatusMeaning
204 No Contentlogin success
400 Bad Requestusername invalid by Scratch standards or request body was malformed
403 Forbiddencomment not found on profile or CSRF tokens didn't match
JSON Body Params
FieldTypeDescription
csrfstrthe CSRF token provided by PUT /login/{username}
Returns nothing

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.

Authorization necessary
GET /applications
HTTP statuses
StatusMeaning
200 OKhere's the list
401 Unauthorizedthis 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.

Authorization necessary
GET /applications/{client_id}
URL Params
FieldTypeDescription
client_idintthe client ID of the application to get
HTTP statuses
StatusMeaning
200 OKhere's the info
401 Unauthorizedthis session is not logged in (click the lock above)
404 Not Foundno 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.

Authorization necessary
PUT /applications
HTTP statuses
StatusMeaning
200 OKnew application's info
400 Bad Requestrequest body was malformed
401 Unauthorizedthis session is not logged in (click the lock above)
JSON Body Params
FieldTypeDescription
app_namestr?name of the app, or null for no name
redirect_urisstr[]?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.

Authorization necessary
PATCH /applications/{client_id}
URL Params
FieldTypeDescription
client_idintthe client ID of the application to update
HTTP statuses
StatusMeaning
200 OKApplication after update
400 Bad Requestrequest body was malformed
401 Unauthorizedthis session is not logged in (click the lock above)
404 Not Foundno such client ID belonging to you, valid or not
JSON Body Params
FieldTypeDescription
reset_secret?boolsetting 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.

Authorization necessary
DELETE /applications/{client_id}
URL Params
FieldTypeDescription
client_idintthe client ID of the application to delete
HTTP statuses
StatusMeaning
204 No Contentit is done
401 Unauthorizedthis session is not logged in (click the lock above)
404 Not Foundno such client ID belonging to you, valid or not
Returns nothing

Authorization Endpoints

For doing The Actual Thing!

Request Refresh Token Endpoint

Request an access and refresh token together.

POST /tokens
HTTP statuses
StatusMeaning
200 OKtoken information
400 Bad Requestrequest body was malformed
401 Unauthorizedclient ID/secret combo is not valid
404 Not Foundinvalid token-getter code
417 Expectation Failedscopes passed in body did not match scopes that user allowed
JSON Body Params
FieldTypeDescription
client_idintclient ID of the app requesting these tokens
client_secretstrclient secret of said app
codestrtoken-getter code passed to the redirect URI after successful authorization
scopesstr|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.

PATCH /tokens
HTTP statuses
StatusMeaning
200 OKnew token information
400 Bad Requestrequest body was malformed
401 Unauthorizedclient ID/secret combo is not valid
404 Not Foundno such refresh token
410 Gonerefresh token is expired
JSON Body Params
FieldTypeDescription
client_idintclient ID of the app requesting this token
client_secretstrclient secret of said app
refresh_tokenstrrefresh 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.

Authorization necessary
GET /user
HTTP statuses
StatusMeaning
200 OKthe username
203 Non-Authoritative Informationwe stored their username, but the comments API 404ed so they could be banned or deleted or renamed
401 Unauthorizedmissing/incorrect authorization (click the lock above)
403 Forbiddeninvalid scopes for this access token
404 Not Foundwe literally don't have any information about this user that you're allowed access to
Returns an User object
{ "user_id": 10114764, "user_name": "kenny2scratch" }

Object Reference

Application Object

An application.

Application Structure
FieldTypeDescription
client_idintthe client ID
client_secretstrthe client secret
created_atintUnix timestamp when this application was created
app_namestr?the app name - can be null, in which case authorization will display [unnamed application] as the app name
flagsintapplication flags, bitwise ORed together
redirect_urisstr[]a list of redirect URIs (which can be empty)

PartialApplication Object

A partial application object.

PartialApplication Structure
FieldTypeDescription
client_idintthe client ID
app_namestr?the app name

Code Object

Data used for API Scratch login.

Code Structure
FieldTypeDescription
usernamestrthe username being logged in
csrfstra CSRF token
codestrthe code to comment on the profile

Tokens Object

Token data from an authorization endpoint.

Tokens Structure
FieldTypeDescription
access_tokenstrthe user access token
access_expiryintUnix timestamp when access token expires
refresh_tokenstrthe refresh token
refresh_expiryintUnix timestamp when refresh token expires
scopesstr[]array of scopes granted to this token pair

User Object

Username data for a Scratch user.

User Structure
FieldTypeDescription
user_idintScratch user ID
user_namestrScratch username (non-authoritative if 203)

AppFlags

Application flags
Name Value Description
NAME_APPROVED1 << 0Whether the app's name has been moderated and vetted. Authorization will display [application name unmoderated] until it has, unless the name is null.
VERIFIED1 << 1Apps with this flag will have a superscript checkmark to distinguish them from potential impostors.
HIDE_OWNER1 << 2By 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
The Wiki is working on a dark theme, and you're seeing it! Got feedback? Post on the forum Community Portal.