Getting Started with Developer Portal - Editor

Create a project

Run:

Code
npx create-zuplo-api@latest my-api-project
cd my-api-project
npm run dev

When prompted, choose Yes to create a matching Portal project, complete sign-in, and select your Zuplo account. The CLI creates a hosted project and links your local copy to it. Keep .env.zuplo out of source control.

The default template includes a Todo API and a developer portal. Open the Docs Server URL printed in the terminal, normally http://localhost:9200. You should see the Todo API reference. The gateway runs on port 9000 and the Route Designer on 9100.

Set your portal's title and introduction

Open docs/zudoku.config.tsx. Set site.title and metadata.title to Todo Developer Portal, and set metadata.description to Explore the Todo API and manage your API keys. Keep the other settings.

The apis entry already reads ../config/routes.oas.json and publishes it at /api. Your API documentation updates when the OpenAPI file changes.

Replace docs/pages/introduction.mdx with:

docs/pages/introduction.mdx
---
title: Welcome to the Todo API
description: Sign in, find your API key, and make your first request.
---

Use the Todo API to retrieve tasks for your application.

1. Sign in using the email address registered as a key manager.
2. Open **API Keys** from your profile menu to find your assigned key.
3. Open **API Reference** and try **Get all todos** with that key.

The default navigation already includes introduction. Open http://localhost:9200/introduction to see the page. Changes appear as you save. See Writing content for more page options.

Require an API key for the sample route

Replace the empty policy list with:

config/policies.json
{
  "policies": [
    {
      "name": "api-key-auth",
      "policyType": "api-key-inbound",
      "handler": {
        "export": "ApiKeyInboundPolicy",
        "module": "$import(@zuplo/runtime)",
        "options": { "allowUnauthenticatedRequests": false }
      }
    }
  ]
}

In config/routes.oas.json, find paths["/todos"].get. Update its x-zuplo-route to retain the forward handler and add the policy:

Code
"x-zuplo-route": {
  "corsPolicy": "anything-goes",
  "handler": {
    "export": "urlForwardHandler",
    "module": "$import(@zuplo/runtime)",
    "options": { "baseUrl": "https://todo.zuplo.io" }
  },
  "policies": { "inbound": ["api-key-auth"] }
}

If you're using an existing project, add the policy to its existing list and put it first in this route's inbound chain. Leave the other routes and their handlers in place.

anything-goes enables browser requests from the developer portal. For a production API, configure CORS for your portal's origin. This step protects GET /todos; apply authentication to other routes before exposing private data through them.

Update info.description to say that GET /todos requires a bearer API key, replacing the sample's statement that no authentication is required.

In a second terminal, run curl -i http://localhost:9000/todos. Expect 401 Unauthorized.

Create a consumer in the Portal

Open your project in the Zuplo Portal and go to Services → API Keys → Consumers. Select Dev, then click Create Consumer.

Set Subject to tutorial-consumer, add your email address under Key managers, and leave Metadata as {}. Click Save consumer.

Key managers can view and manage this consumer's keys after signing in to the developer portal. Signing in alone doesn't create a consumer. See API key management.

Sign in to the developer portal

Open http://localhost:9200 and sign in with the same email address you entered as a key manager. The template includes a demo sign-in provider and apiKeys: { enabled: true } for this test.

Open your profile menu and select API Keys. The assigned consumer and its key should appear. If they don't, check the email address and that you created the consumer in Dev for the linked project.

Call the API from the documentation

Open API Reference, select Get all todos, and click Test. Expand Authentication, select tutorial-consumer, and click Send. Expect 200 OK and a JSON response containing todos.

You can also copy the key and verify it from a second terminal:

Code
export TODO_API_KEY="YOUR_API_KEY"
curl -i http://localhost:9000/todos \
  -H "Authorization: Bearer $TODO_API_KEY"

This request should return 200; the same request without the header should still return 401.