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.
Your application has both a public
client_id and a private
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
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.
You must declare your desired level of account permissions via the
scope can be one of the following values:
You may only inspect data on a user’s account.
Full API access to this user’s account. You can use methods
This scope level will return a grant object to you containing the
Your requested scope will be explicitly shown to the user.
Only request least invasive scope that you need.
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:
Should contain the value
The location that Scryfall should redirect the browser when
the user submits a confirmation.
Must be an
with Scryfall in your application’s
The level of access that you need for this account.
The authorization page will display your requested
access level to the user.
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
provided, and the followings parameters will be added to the URI:
||String||The secret access code you can use to continue the OAuth workflow in step 3, if the user approved your access.|
The value of the
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.