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


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