# Registering an application

> Three ways to obtain an OAuth client: curated templates, provider installations, and dynamic self-registration.

> **Preview / beta**
>
> The Application Marketplace is under active development and may change without long deprecation windows. See the [Application Marketplace overview](/docs/platform/integrations/marketplace).

Before any OAuth flow can start, your application needs a client registered against the provider you want to operate with. A client is an OAuth `client_id` (plus a `client_secret` for confidential clients) and a set of registered redirect URIs, scoped to one provider.

There are three ways to obtain a client. Which ones are available depends on the provider's configuration (each is enabled independently). Whichever path you take, everything after registration is identical.

## The three registration paths

| Path                  | Who creates it                                                              | Best for                                                                        |
| --------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Curated template      | Road staff create the catalogue entry; a provider administrator installs it | An application you want offered as a vetted, consistent option across providers |
| Provider installation | A provider administrator defines and registers it                           | An application bespoke to a single provider                                     |
| Dynamic registration  | Your application self-registers (RFC 7591)                                  | Self-service onboarding where the provider has enabled it                       |

## Curated templates (Road-vetted)

If you want your application to appear as a pre-defined option in the Road catalogue, visible to providers as a one-click target with consistent branding, Road staff create a template for it. When a provider administrator installs from the template, the descriptive fields (logo, homepage URL, privacy policy URL) come from the template and are locked. The provider can override the customer-facing name and description, choose redirect URIs, and pick scopes within the template's maximum set.

> **Want your application in the curated catalogue?**
>
> Contact us at <ere.marketplace@road.io> with the metadata you would like to register (name, description, logo, homepage URL, privacy policy URL, and the scopes you intend to request). Once vetted, Road creates the template and provider administrators can install it.

## Provider installations (provider-defined)

A provider administrator can register an application of their own from the Road dashboard. They own all of the metadata (name, description, logo, homepage URL, privacy policy URL), choose the redirect URIs, and pick which scopes the application may request. The provider then shares the generated `client_id` and one-time `client_secret` with you, securely and out of band.

This is the right path when you are an internal team or a partner of a single provider and the application does not need to appear as a vetted catalogue entry elsewhere.

## Dynamic client registration (RFC 7591)

Where a provider has enabled it, an application can register itself with no administrator involvement, using standard [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591) Dynamic Client Registration.

### The registration endpoint

```http
POST https://api.road.io/1/oauth/{{providerSlug}}/register
Content-Type: application/json

{
  "client_name": "My Application",
  "redirect_uris": ["https://app.example/callback"],
  "token_endpoint_auth_method": "none",
  "scope": "openid offline_access sessions:read chargers:read"
}
```

A successful call returns `201` with the `client_id`, a `registration_access_token`, and a `registration_client_uri`. The registration endpoint only appears in the provider's discovery document when dynamic registration is enabled; when it is off the endpoint returns `404`.

### Managing a registration (RFC 7592)

The `registration_access_token` lets the application read, update, or delete its own registration using standard [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592):

```http
GET    https://api.road.io/1/oauth/{{providerSlug}}/register/{client_id}
PUT    https://api.road.io/1/oauth/{{providerSlug}}/register/{client_id}
DELETE https://api.road.io/1/oauth/{{providerSlug}}/register/{client_id}
Authorization: Bearer {registration_access_token}
```

A `PUT` fully replaces the metadata and rotates the `registration_access_token`; store the new one and discard the old. A `DELETE` deregisters the client and revokes the grants issued to it.

### Public clients only (today)

Dynamic registration currently supports public clients only: `token_endpoint_auth_method` must be `none`. There is no client secret, so the application is authenticated at the token endpoint by PKCE alone. See [Authenticating your application](/docs/platform/integrations/marketplace/authentication) for what that means in practice.

### Gated scopes

Most scopes are open: any application can self-register for them where dynamic registration is enabled. A small number of higher-value scopes are **gated**: they cannot be requested via dynamic registration, and a `register` call that asks for one is rejected with `400 invalid_client_metadata`. To use a gated scope your application must be registered as a **curated template** or a **provider installation**, both of which are vetted by a person before the scope is available.

Gated today:

| Scope | Available through                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------------------------- |
| `ere` | Curated template or provider installation only. See [ERE integration](/docs/platform/charge-point-operation/ere-integration). |

This keeps the platform open by default while letting Road reserve specialised data surfaces for approved integrations. Expect the gated set to grow as new specialised scopes land. To request access to a gated scope, contact us at <ere.marketplace@road.io>.

## What you receive

After registration you will have:

1. A **`client_id`**.
2. A **`client_secret`**, for confidential clients only (provider installations and templates). Dynamic (public) clients have none.
3. The **discovery URL**, `https://api.road.io/1/oauth/{{providerSlug}}/.well-known/openid-configuration`. Fetch it once to get the rest of the OIDC endpoints.

There is no global client. Every provider you operate with gives you a distinct credential pair and issuer URL; the same application code is reused across providers.

## After registration, the flow is identical

Regardless of which path created the client, the authorisation, consent, token, and data-access steps are exactly the same. Continue with [Authenticating your application](/docs/platform/integrations/marketplace/authentication).

## Get in touch

To list a curated template, or to ask a provider to enable a registration path, contact us at <ere.marketplace@road.io>.