Applications
OAuth and registered API applications are currently in private beta. Public registration for applications is not currently available.
Some Scryfall API methods are restricted to valid applications, and registered applications receive increased API limits.
In addition, your application can implement an OAuth workflow that allows people with Scryfall accounts to grant your application programatic access to their data.
Application Secrets
Your application has both a public client_id and a private client_secret.
Never share your client_secret with anyone outside your organization,
and make sure not to accidentally commit your secret to source control
or other public code sharing environments.
OAuth Workflow Summary
You can request that someone with a Scryfall account grant your application access to their account data. Once you receive a grant, you can call Scryfall API methods that require account credentials as if you were that person.
The workflow is as follows:
Send the person’s browser to
https://scryfall.com/oauth/authorizewith your application’s specific parameters in the URL.If the user grants your application access, we will redirect their browser back to your website with a secret code in the URL.
Your server should call the
/oauth/convertmethod and provide the code you just received. Scryfall’s API will respond with an OAuth grant object that includes credentials that your application can use to access the person’s account on their behalf.Call other API methods on behalf of the account.
OAuth Scope
You must declare your desired level of account permissions via the scope parameter.
The scope can be one of the following values:
| Scope | Description |
|---|---|
|
You may only inspect data on a user’s account. No methods that change data will be allowed. |
|
Full API access to this user’s account. You can use methods that update, delete, and add account data on behalf of the user. |
|
This scope level will return a grant object to you containing the user’s public account information, and then revoke your access to their account immediately afterward. Useful for creating software such as polls or petitions that only need to make sure that a unique and valid account is signing or voting as a one-time action. |
Your requested scope will be explicitly shown to the user.
Only request least invasive scope that you need.
Requesting read_write may lead to additional user rejections
if it is not apparent why your application needs that access level.
1. OAuth Authorization Prompt
Provide a button or a link such as “Sign in with Scryfall” on your website or in your application.
Redirect the user to https://scryfall.com/oauth/authorize. Add the following
parameters to the URI:
| Parameter | Type | Atn | Details |
|---|---|---|---|
client_id
|
UUID |
Your application’s client_id.
|
|
response_type
|
String |
Should contain the value code.
|
|
redirect_uri
|
URI |
The location that Scryfall should redirect the browser when
the user submits a confirmation.
Must be an https:// URI that you have pre-registred
with Scryfall in your application’s redirect_uris.
|
|
scope
|
String |
The level of access that you need for this account.
Must be ephemeral, read or read_write.
The authorization page will display your requested
access level to the user.
|
|
state
|
String | Optional | An optional arbitrary string, up to 128 characters in length, that we will return back to your server when the user confirms access. Useful for preventing cross-site request forgery attacks. |
2. OAuth Redirect
The user’s browser will be redirect to the redirect_uri you
provided, and the followings parameters will be added to the URI:
| Parameter | Type | Atn | Details |
|---|---|---|---|
status
|
String |
Will be success if the user approved your access, or access_denied if the user rejected your request.
|
|
code
|
String | The secret access code you can use to continue the OAuth workflow in step 3, if the user approved your access. | |
state
|
String | Optional |
The value of the state parameter you provided in step 1.
|
3. Convert the Code
Call the API method /oauth/convert to exchange the code you just received
for long-lived credentials.
The API server will reply with a detailed object about your access level.
See the documentation for /oauth/convert for full more information.
4. Call Other Methods as the User
You can now call other API methods on behalf of the account in question. See the Authorization article for more information.