APIs

An API in Optare represents a protected resource that your applications can access. Define APIs to enable fine-grained authorization with scopes.

Why Define APIs?

When you define an API, you can:

• Issue access tokens with specific audience claims
• Control which applications can access which resources
• Define custom scopes for granular permissions

Create an API

1. Go to Optare Console (opens in a new tab)
2. Navigate to APIs
3. Click Create API

API Settings

Scopes

Scopes define what actions can be performed on the API.

Create Scopes

Best Practices

• Use resource:action format (e.g., read:projects)
• Keep scopes granular
• Avoid catch-all scopes like *

Using APIs

Request Token with Audience

const { accessToken } = await client.auth.getToken({
  audience: 'https://api.myapp.com',
  scope: 'read:users write:users',
});

Validate in Your API

const { payload } = await jose.jwtVerify(token, JWKS, {
  audience: 'https://api.myapp.com',
  issuer: 'https://id.optare.one',
});
 
// Check scopes
const scopes = payload.scope?.split(' ') || [];
if (!scopes.includes('read:users')) {
  throw new ForbiddenError('Missing read:users scope');
}

Machine-to-Machine (M2M) Access

For backend services accessing your API:

1. Create an M2M application
2. Authorize it to access your API
3. Grant specific scopes

const token = await client.auth.getM2MToken({
  clientId: 'service_client_id',
  clientSecret: process.env.SERVICE_SECRET,
  audience: 'https://api.myapp.com',
  scope: 'read:users',
});

Next Steps

• Applications - OAuth client setup
• Node.js Quickstart - Validate tokens
• RBAC - Role-based access control