Registering an application

Preview / beta

The Application Marketplace is under active development and may change without long deprecation windows. See the Application Marketplace overview.

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 [email protected] 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 Dynamic Client Registration.

The registration endpoint

POST https://api.road.io/1/oauth/road/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:

GET    https://api.road.io/1/oauth/road/register/{client_id}
PUT    https://api.road.io/1/oauth/road/register/{client_id}
DELETE https://api.road.io/1/oauth/road/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 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.

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 [email protected].

What you receive

After registration you will have:

A client_id.
A client_secret, for confidential clients only (provider installations and templates). Dynamic (public) clients have none.
The discovery URL, https://api.road.io/1/oauth/road/.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.

Get in touch

To list a curated template, or to ask a provider to enable a registration path, contact us at [email protected].