canonical: https://jentic.com/apis/franceconnect.gouv.fr/franceconnect

# FranceConnect API

FranceConnect is the French government's identity federation service that lets citizens sign in to public and private service providers using credentials they already hold (impots.gouv.fr, ameli, La Poste, MSA). The API implements OpenID Connect with seven endpoints covering discovery, authorisation, token exchange, user info, JWKS, and session termination. Service providers integrate against version 2 to authenticate users and receive verified identity claims (given name, family name, birthdate, birthplace, gender, email).

## For AI agents

Authenticate French citizens via OpenID Connect against FranceConnect and exchange the resulting code for an ID token plus verified identity claims. Bearer-token authorisation on the userinfo endpoint.

## Scope

Does not handle document verification, biometric matching, or proof-of-address checks - use for OpenID Connect federation against French government identity providers only.

## Capabilities

- Redirect users to /authorize to start an OpenID Connect login against FranceConnect identity providers
- Exchange an authorisation code for an ID token and access token at /token
- Fetch verified identity claims (given_name, family_name, birthdate, birthplace, gender, email) from /userinfo
- Discover endpoint URLs and supported scopes via /.well-known/openid-configuration
- Validate ID token signatures using the JWKS published at /jwks
- Terminate the user's FranceConnect session through `/session/end` so single sign-out propagates

## Use cases

### Public Service Login Federation

A French e-government service redirects users to FranceConnect, lets them choose any approved identity provider, and receives back a signed ID token plus verified civil-status claims. The integration replaces a custom login flow with a state-recognised identity check that satisfies eIDAS substantial assurance.

Example prompt: Build the /authorize redirect URL with client_id, redirect_uri, scope=openid profile email, then exchange the returned code at /token for an id_token

### Private-Sector KYC Onboarding

A French bank or insurer uses FranceConnect to verify a new customer's civil status without asking them to upload ID documents. After the user authenticates, /userinfo returns government-validated given name, family name, and birthdate that can be persisted to the customer record. This shortens onboarding from days to minutes.

Example prompt: Call GET /userinfo with the bearer access_token returned from /token and persist the given_name, family_name, birthdate, and birthplace claims to the customer record

### Single Sign-Out Across Government Sites

When a user logs out of one FranceConnect-federated service, the session must end across all other FranceConnect sessions. Calling `/session/end` with the id_token_hint terminates the federated session and notifies other relying parties, which is mandatory for compliance with the FranceConnect technical specification.

Example prompt: Redirect the user to `/session/end`?id_token_hint={id_token}&post_logout_redirect_uri={return_url} to terminate the FranceConnect session

### AI Agent Identity Verification

An agent acting on behalf of a French citizen uses FranceConnect through Jentic to obtain verified civil-status claims, then calls a downstream administrative API on the user's behalf. Jentic isolates the client_secret in the vault and returns only the resolved identity claims to the agent's context.

Example prompt: Search Jentic for 'authenticate a French user via FranceConnect', execute the /authorize and /token flow, and return the verified userinfo claims

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/.well-known/openid-configuration` | Read the OpenID Connect discovery document |
| GET | `/authorize` | Start the OpenID Connect authorisation flow |
| POST | `/token` | Exchange an authorisation code for an ID token |
| GET | `/userinfo` | Fetch verified identity claims for the authenticated user |
| GET | `/jwks` | Retrieve the JSON Web Key Set for ID token validation |
| GET | `/session/end` | Terminate the FranceConnect session |

## Key resources

- **Authorization** — Initiate OpenID Connect login flows via /authorize
- **Token** — Exchange authorisation codes for ID tokens and access tokens
- **UserInfo** — Retrieve verified civil-status claims for the authenticated user
- **Discovery** — Read the OpenID Connect configuration document
- **Session** — Terminate FranceConnect sessions for single sign-out

## Why Jentic

- **Setup:** Wiring the FranceConnect API by hand means implementing the full OpenID Connect flow across /authorize, /token, and /userinfo, managing the bearer token, and building your own retry and error handling. Through Jentic you install once, import FranceConnect from the API Directory, store the relying-party credentials once, and your agent calls it.
- **Permission scoping:** FranceConnect is an OpenID Connect federation with fixed flow endpoints and carries its parameters in the query and request body rather than as path resources, so scoping is operations-only: you limit the agent to the operations it needs, such as /authorize, /token, and /userinfo, and leave out session end unless you add it. Every operation the agent can run is one you chose.
- **Credential handling:** Your FranceConnect client_id and client_secret are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'authenticate a French user', and Jentic returns the matching FranceConnect operations (/authorize, /token, /userinfo) with their input schemas so the agent completes the OIDC flow without parsing the spec.

## Related APIs

- **Auth0** — Auth0 provides general-purpose OpenID Connect identity rather than French civil-status federation
- **ID.me** — ID.me is the equivalent identity federation service for US government and commercial relying parties
- **Okta** — Okta can broker FranceConnect as one of several upstream identity providers in an enterprise SSO setup

## FAQ

### What authentication does the FranceConnect API use?

FranceConnect implements OpenID Connect. The /token endpoint authenticates the relying party with client_id and client_secret, and /userinfo accepts the access token as a bearer token in the Authorization header. Through Jentic, the client_secret is stored encrypted in the vault and never reaches the agent.

### Can I retrieve a French user's civil-status claims with the FranceConnect API?

Yes. After completing the OpenID Connect flow, call GET /userinfo with the bearer access_token. The response includes given_name, family_name, birthdate, birthplace, gender, and email - all verified by an upstream French identity provider such as impots.gouv.fr or ameli.

### What are the rate limits for the FranceConnect API?

FranceConnect does not publish hard per-client rate limits in its specification. Production access is gated by a partnership agreement with DINUM and the limits are negotiated per use case; staging environments accept a few requests per second.

### How do I terminate a FranceConnect session through Jentic?

Search Jentic for 'end FranceConnect session', load the `/session/end` schema, and execute it with the id_token_hint returned earlier from /token. FranceConnect propagates the logout to other federated relying parties so single sign-out is enforced.

### Is the FranceConnect API free?

FranceConnect is provided free of charge to French public-sector services and to private-sector relying parties that meet the eligibility criteria defined by DINUM. Onboarding requires a signed convention de service before production credentials are issued.

### How do I validate a FranceConnect ID token signature?

Fetch the JWKS document from GET /jwks, locate the key with the matching kid header on the ID token, and verify the RS256 signature. The discovery document at /.well-known/openid-configuration tells you which signing algorithms are advertised for the current environment.

### Can I limit what my agent is allowed to do with the FranceConnect API?

Yes. Because you run Jentic One yourself, your own rules decide which FranceConnect operations the agent can call and which credentials it may use. FranceConnect is an OpenID Connect federation with fixed flow endpoints, so scoping is operations-only: you can allow just the operations the agent needs, such as /authorize, /token, and /userinfo, and leave out `/session/end` unless you deliberately add it. Every operation the agent can run is one you chose, and your relying-party client_id and client_secret stay in your own instance rather than the agent's context.