POST /oauth/reg

Register your app with Coil

After we approve your use case you can register your app with us.

note

Review this section carefully. Steps 1 - 3 might already be complete.

  1. Sign up for a free Coil account if you don't already have one.
  2. Email [email protected] and outline your use case.
  3. Wait for approval.
  4. When approved, sign in to your Coil account and then visit https://coil.com/oauth_register.
  5. Fill out the form. All fields are mandatory.
FieldDescription
Client App NameThe name of your app that you'll show to Coil users while they are authenticating.
Redirect URIsA CSV list of URIs that Coil users can be redirected to after granting access to their resources.
Logo URIThe URI of your app's logo. The logo is shown to Coil users so they know which app is requesting access to their resources.
  1. Wait for your registration access token. After you have the token, register your app with the Coil OIDC provider to exchange the token for a client ID and client secret.

Register your app with the OIDC provider

Client apps that want to use resources owned by Coil must register themselves with our OIDC provider.

POST https://coil.com/oauth/reg

The header of your request must include the access token we emailed you.

danger

This request can only be made once. Make sure you save the client_id and client_secret returned in the response.

Request

Request headers

NameValue
Content-Typeapplication/json
Authorization BearerBearer REGISTRATION_ACCESS_TOKEN, where REGISTRATION_ACCESS_TOKEN is the token you received via email

Request body

ParameterTypeDescription
redirect_urisarray of stringsThe URIs that Coil users can be redirected to after granting access to their resources. You must include the same redirect URIs you included on the web form.
client_namestringThe name of your app that you'll show to Coil users while they are authenticating.
tos_uristringThe URI to your Terms of Service.
policy_uristringThe URI to your Privacy Policy.
logo_uristringThe URI of your app's logo.

Example request

curl -X POST https://coil.com/oauth/reg \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer Pb8w98v18ikkZyy26nxXK5OKDDsN6kfEJVmQ2id9tbC' \
-d \
'{
"redirect_uris":["https://example.com"],
"client_name": "My App",
"tos_uri": "https://example.com/terms",
"policy_uri": "https://example.com/privacy",
"logo_uri": "https://coil.com/images/icn-coil_1icn-coil.png"
}'

Response

The OIDC provider returns a number of parameters in the response. The most important are below. Make sure you save your client_id and client_secret.

ParameterTypeDescription
client_idstringThe identifier for your app that was registered with the OIDC provider.
client_secretstringThe corresponding secret to the client_id.
redirect_urisarray of stringsThe registered redirect_uris that will be used.

Example response

{
"application_type": "web",
"grant_types": [
"authorization_code",
"refresh_token"
],
"id_token_signed_response_alg": "RS256",
"require_auth_time": false,
"response_types": [
"code"
],
"subject_type": "public",
"token_endpoint_auth_method": "client_secret_basic",
"introspection_signed_response_alg": "RS256",
"post_logout_redirect_uris": [],
"backchannel_logout_session_required": false,
"request_uris": [],
"authorization_signed_response_alg": "RS256",
"web_message_uris": [],
"client_id_issued_at": 1552957330,
"client_id": "314ac134-fc3c-4d28-bf43-ccb75a2f9fb2",
"client_name": "My App",
"client_secret_expires_at": 0,
"client_secret": "uVE2t7y1QvyM78PlBA3aQAUh6syXVw7P2XBr4QDsS2yrkETR6al9YFpH4NDloXh5",
"redirect_uris": [
"https://example.com"
],
"tos_uri": "https://example.com/terms",
"policy_uri": "https://example.com/privacy",
"logo_uri": "https://coil.com/images/icn-coil_1icn-coil.png",
"introspection_endpoint_auth_method": "client_secret_basic",
"revocation_endpoint_auth_method": "client_secret_basic",
"registration_client_uri": "https://coil.com/oauth/reg/9aa42050-aa1e-41ae-b1eb-abc14ed9894f",
"registration_access_token": "84a3LeRtn_x06skdje45~x4m8mdqT1qhSizyqpijrzr"
}

Next: Call GET /oauth/auth to get an access code so your app can request access to an authenticated Coil user's resources.