Getting a DJ's consent

Follow this page to send a DJ to the Spoon consent screen and receive the value that comes back after they allow your app. That value carries a code you exchange for a token in the next step.

Before you start

• The Client ID of a registered app — get it in App registration.
• The login redirect URL you registered for that app — the DJ returns here.

How the flow runs

Your bot server ──▶ Send the DJ's browser to the authorize URL
                         │
                         ▼
                   Spoon handles login and the consent screen
                         │
                         ▼
Your redirect URL ◀── The browser returns with a code or an error

Spoon draws the login and consent screens. Your server does two things: send the DJ and read what comes back.

1. Send the DJ to the consent screen

Move the DJ's browser to the URL below. This is a page the browser opens, not an API your server calls.

https://developers.spooncast.net/kr/oauth/authorize
  ?response_type=code
  &client_id={Client ID}
  &redirect_uri={login redirect URL}
  &scope=events.chat%20chat.send
  &state={a random value you generate}

Put the region in the URL. Korean apps use /kr, Japanese apps use /jp.

Region	authorize URL
Korea	https://developers.spooncast.net/kr/oauth/authorize
Japan	https://developers.spooncast.net/jp/oauth/authorize

Use the region your app is registered in. Sending a DJ to another region's URL means they must sign in with an account from that region, so they never reach the consent screen.

Parameter	Required	Rules
response_type	Required	Only code is accepted.
client_id	Required	The Client ID from your app detail page.
redirect_uri	Required	Must match the URL you registered, character for character. If it differs, the consent screen shows an error and the DJ does not return to your URL.
scope	Required	List the permissions you want, separated by spaces. Encode the spaces as %20 in the URL. Permissions your app has not registered are rejected.
state	Recommended	A fresh random value per request. It comes back unchanged, so compare it to reject forged requests. Accepts up to 512 bytes.

Send DJs who are not signed in as well. Spoon takes them through login and on to the consent screen.

A DJ who already granted the same permissions returns without seeing the screen. Consent accumulates, so only newly requested permissions appear.

2. Read what comes back

The DJ's browser returns to your redirect_uri. Tell success from failure by the query.

When the DJ allows your app, a code arrives.

https://my-bot.example.com/callback?code=9d41f7a0c86b23e5...&state=the-value-you-sent

Value	What it is for
code	A single-use value you exchange for a token. Use it within 60 seconds.
state	Exactly the value you sent. Discard the request if it differs.

When the DJ declines, or the request is wrong, an error arrives instead of a code.

https://my-bot.example.com/callback?error=access_denied&state=the-value-you-sent

error	What happened	What to do
access_denied	The DJ did not allow your app.	Stop the flow and tell the DJ. Trying again is fine.
invalid_scope	You asked for a permission your app does not hold.	Narrow scope to the permissions registered for your app. Sending it again returns the same result.

Some failures arrive without an error. When the client_id or redirect_uri cannot be trusted, Spoon shows the error on its own consent screen instead of returning to your URL. This keeps users from being sent to unregistered addresses. The DJ never reaches your service in that case, so check the Client ID and redirect URL before you send anyone.

Check that it works

Open the authorize URL in a browser. The flow is wired correctly when this happens.

1. The Spoon login screen appears, or the consent screen appears directly if signed in.
2. Only the permissions not yet granted appear in the list.
3. Allowing sends the browser back to your redirect_uri with code and state.

If an error message appears instead of the consent screen, check client_id and redirect_uri again.

Next step

Exchange the code for a token. The code is valid for 60 seconds, and once used it cannot be used again.