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:

  1. Send the person’s browser to https://scryfall.com/oauth/authorize with your
    application’s specific parameters in the URL.

  2. If the user grants your application access, we will redirect
    their browser back to your website with a secret code in the URL.

  3. Your server should call the /oauth/convert method 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.

  4. 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

read

You may only inspect data on a user’s account.
No methods that change data will be allowed.

read_write

Full API access to this user’s account. You can use methods
that update, delete, and add account data on behalf of the user.

ephemeral

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.