Your first request

This walks you through the whole flow by hand for an app that runs on a server, so you can see every step. In a real app, an OAuth library will do most of this for you.

You'll need your app's client ID and client secret from Settings → Developers. Building an app that runs in a browser or on a phone? Follow Your first request from a browser or phone instead.

1. Ask for access

Open this link in your browser, with your own client ID and one of your redirect links:

https://streetartcities.com/api/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://example.com/callback
  &scope=collections:read
  &state=anything-random

Log in if needed and click Allow. You end up on your redirect link, with a code added to it:

https://example.com/callback?code=3kW9...&state=anything-random

2. Swap the code for a token

The code only works once, and only for 10 minutes:

curl -X POST https://streetartcities.com/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "THE_CODE",
    "redirect_uri": "https://example.com/callback",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

You get back:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "Yh1c...",
  "scope": "collections:read"
}

3. Call the API

Send the access token in the Authorization header:

curl https://streetartcities.com/api/collections \
  -H "Authorization: Bearer ACCESS_TOKEN"

That's it: you've got the person's collections. From here, read up on tokens to keep people logged in, or explore the Edits API.

To see the same flow in code, take a look at our demo app. It's a small Node.js server that does all of the above, and then suggests a change with the Edits API.