Street Art Cities edits demo

A minimal example app that lets people suggest changes to Street Art Cities from your own app. It covers the whole flow:

1. Sign in with Street Art Cities using OAuth 2.0 (authorization code flow with PKCE).
2. Suggest a change to an artwork with the Edits API.
3. Send the user to the reviewUrl, where they can approve the change or follow its review.

It's a single server.js file with no dependencies, so you can read the whole integration in a few minutes and adapt it to your framework of choice.

For the full documentation, see developers.streetartcities.com.

Running it

You need Node.js 20.6 or newer.

1. Create an app under Settings → Developers. Choose "on a server" and add http://localhost:3000/callback as a redirect link.

2. Copy .env.example to .env and fill in your client ID and secret.

3. Start the app:

   npm start

4. Open http://localhost:3000, sign in, paste a link to an artwork and suggest a change.

How it works

1. Signing in

Send the user to the authorize page:

GET https://streetartdev.com/api/oauth/authorize
  ?response_type=code
  &client_id=<your client id>
  &redirect_uri=http://localhost:3000/callback
  &scope=edits:write
  &state=<random string>
  &code_challenge=<base64url(sha256(code_verifier))>
  &code_challenge_method=S256

The demo only asks for edits:write, which lets it suggest changes. Ask only for the scopes your app needs.

Once they allow access, they come back to your redirect_uri with ?code=…&state=…. Check that state matches the value you sent, then swap the code for tokens from your server:

POST https://streetartdev.com/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<code>
&redirect_uri=http://localhost:3000/callback
&code_verifier=<code_verifier>
&client_id=<your client id>
&client_secret=<your client secret>

You get back an access_token, which lasts an hour, and a refresh_token, which lasts 30 days. When the user signs out, the demo revokes the refresh token. See Tokens for refreshing and revoking.

Keep your client secret on the server. Never send it to the browser, put it in a mobile app or commit it to a repository.

More details: The OAuth flow.

2. Suggesting a change

Call the Edits API with the access token:

POST https://streetartdev.com/api/edits
Authorization: Bearer <access token>
Content-Type: application/json

{
  "entityType": "marker",
  "entityId": "ee12872f-099f-4d0f-96c5-8983b314c3f9",
  "actions": {
    "attributes.access_note": "Only accessible whilst the shop is open.",
    "tags": { "$add": ["stencil"] }
  },
  "editComment": "Visited today, the gate was closed."
}

• entityType is what you're changing. marker is an artwork.
• actions maps fields to their new values.
• Leave out entityId to suggest a new artwork.

More details: Suggesting changes and the Create edit reference.

3. Sending the user to review it

Edits made through an app are never applied straight away: they always come back with "status": "submitted". The response includes a reviewUrl:

{
  "edit": {
    "id": "…",
    "status": "submitted",
    "reviewUrl": "https://streetartdev.com/…",
    …
  }
}

Redirect the user there. If they're allowed to review the edit, they can accept it right away. If not, the page shows its status while it waits for review.

More details: The review queue.

Environments

	Base URL
Development	https://streetartdev.com
Production	https://streetartcities.com

Set SAC_BASE_URL in .env to switch. You need a separate app in each environment.

Taking this further

This demo keeps things short on purpose. In a real app you'll also want to:

• Store sessions and tokens somewhere that lasts, like a database, instead of in memory.
• Use HTTPS and mark your session cookie Secure.
• Make sure only one token refresh happens at a time. Each refresh token works once.
• Handle the Edits API's 400, 403 and 404 errors in a way that makes sense to your users.