OAuth API

Overview

The Coil OAuth API is primarily used for sites that have already taken the step to set up Web Monetization and want to offer a way for Coil Members to access monetized content on mobile and on desktop without the Coil Extension installed.

You can implement basic Web Monetization on your site without access to our OAuth API.

If you're already familiar with Web Monetization, read about our OAuth Web Monetization Script. The script is available for any site that uses Coil's OAuth and allows users to sign in to their Coil account from your site.

Getting started

Before you can use the API, you must send an email to devs@coil.com outlining your use case.

After you are approved for OAuth access, register your client app and wait for a registration access token. You must then use the access token to register your app with the Coil OpenID Connect (OIDC) provider. The registration process is outlined on the POST /oauth/reg page.

OpenID Connect settings

The Coil OIDC and OAuth2 provider uses the oidc-provider package, which implements the specs described by openid.net.

Openid-configuration is the Coil OIDC provider's discovery document. The document describes the API endpoints used during the authentication sequence. You'll need these details to construct requests to the server. Specifying this URL connects the authenticator to the OIDC provider.

Setting

Value

Discovery Endpoint

https://coil.com/.well-known/openid-configuration

Authorization Scopes

simple_wm, email, and openid

Authorization scopes

simple_wm

For most use cases, simple_wm provides everything you'll need to authorize a Coil user to make streaming payments without the Coil Extension. The majority of OAuth access requests will be approved to use simple_wm.

The simple_wm scope provides a Coil user's unique, permanent ID and a BTP token. The BTP token allows an Interledger Protocol (ILP) stream to open so that Coil can make payments on behalf of the Coil user.

Simple_wm respects the privacy of Coil users by keeping their details private while enabling them to stream payments on more platforms.

email

The email scope provides you with the Coil user's email address and can be used along with simple_wm.

openid

Openid is a required scope for any OAuth grant but no permissions are attached to it.

Basic OAuth flow

The Coil OIDC and OAuth2 provider uses the authorization code flow to grant access to resources owned by Coil users.

  1. Email devs@coil.com and outline your use case.

  2. Wait for approval.

  3. When approved, register your client app and wait for your registration access token.

  4. After you have a registration access token, register your app with the Coil OIDC provider to exchange the token for a client ID and client secret.

  5. Get permission for your app to access resources owned by a Coil user.

  6. Request an access token.

  7. Get the resources that the app was previously granted access to.

  8. Issue the Coil user a BTP token.

Endpoints