Building an OAuth app

An OAuth app lets your tool act on someone's Ghost account without asking for their password. The person approves the app once, choosing what it may do, and your app receives a token it can call the API with. Ghost speaks GitHub's OAuth: a library or tool written for GitHub OAuth apps works against Ghost once you point it at your Ghost host.

The flow has three parts:

1. You register the app once and get a client ID and a client secret.
2. Your app sends each person to Ghost, where they approve it. Ghost sends them back to your app with a one-time code.
3. Your app exchanges the code, with its secret, for an access token.

In the examples below, api.<domain> is your Ghost API host and <web> is the Ghost web app.

Register the appCopy Anchor Link

Open Settings → OAuth apps and choose New OAuth app.

To register the app for an organization instead, open the organization's settings at <web>/<org>/settings/oauth-apps. Every admin and owner of the organization can see and manage its apps, and people see the organization as the app's owner when it asks for access. Members below admin cannot. When the organization is deleted, its apps go too, and every token they were given stops working.

Fill in the form:

• Application name: what people see when your app asks for access.
• Description: optional. One or two sentences on what the app does, shown on the approval page.
• Homepage URL: your app's website.
• Callback URLs: where Ghost sends people after they approve the app. Add your production callback and, while you develop, a http://localhost one. See Callback URLs for the rules.
• Enable device flow: only for command-line tools and devices that cannot receive a callback. See The device flow.
• Expire user authorization tokens: access tokens last 8 hours and come with a refresh token. See Refreshing tokens.

Choose Register application. Ghost shows the client ID and the client secret.

The app's page then holds everything you can change later: the credentials, a logo, the settings, and deleting the app.

Callback URLsCopy Anchor Link

• Use https://, or http:// on localhost, 127.0.0.1 or [::1] while you develop. Plain http:// on any other host is refused.
• An app can have up to 10 callback URLs.
• When your app names a redirect_uri, it must have the same scheme, host and port as one of the callback URLs, and its path must equal that callback's path or sit under it. With a callback of https://bot.example/oauth/callback:

• When your app names no redirect_uri, Ghost uses the first callback URL.

Next stepsCopy Anchor Link