Getting Started

This guide will walk you through your first interactions with the Covage FTTX API. You will learn how to authenticate and perform an eligibility check.

1. Authentication

How It Works

Authentication is done using an access token, which you retrieve from the authentication request response. We use the OAuth2 protocol for authentication.

You need to obtain an access token using the password flow with the service account credentials that Covage will provide you.

sequenceDiagram participant Client participant Keycloak participant API FTTX Client->>Keycloak: POST /token (credentials) Keycloak->>Client: access_token + refresh_token Client->>API FTTX: GET /api/v1/* (Authorization: Bearer token) API FTTX->>Client: Response

Retrieving the Access Token

Retrieve the access token for the Covage API.

POST {keycloak-url}/auth/realms/covage/protocol/openid-connect/token

Name	Type	Description
Content-Type	string	Request content type (application/x-www-form-urlencoded)

Parameters

Name	Type	Description	Required
grant_type	string	Authentication flow type (password)	Yes
client_id	string	Client identifier (api-client)	Yes
username	string	Service account username	Yes
password	string	Service account password	Yes

Credentials

The username and password are provided by Covage.
The client_id is always api-client for this authentication flow.
The grant_type is always password for this authentication flow.

Response

Name	Type	Description
access_token	string	Access token to use in subsequent requests to authenticate with the API
expires_in	number	Access token lifetime (in seconds)
token_type	string	Token type (Bearer)
refresh_token	string	Refresh token to use to retrieve a new access token
refresh_expires_in	number	Refresh token lifetime (in seconds)
scope	string	Token scope
session_state	string	Session state

Request Example

curl -X POST "{keycloak-url}/auth/realms/covage/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=api-client" \
  -d "username=your_username" \
  -d "password=your_password"

Response Example

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "refresh_expires_in": 7200,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "scope": "email profile",
  "session_state": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

2. Perform an Eligibility Check in 3 Steps

Once authenticated, you can query the API to check a site's eligibility for one or more Covage offer families.

flowchart LR A[1. Get eligibility_id] --> B[2. Create eligibility request] B --> C[3. Consult results] style A fill:#e1f5ff style B fill:#e1f5ff style C fill:#d4edda

Step 1: Get the eligibility_id

The eligibility_id is an identifier that references a site. You can obtain it by querying the /api/v4/eligibility/site/ endpoint with different parameters:

Endpoint: GET /api/v4/eligibility/site/

By GPS Coordinates

curl -X GET "https://api-client.covage.com/api/v4/eligibility/site/?x=1.091455&y=49.4744077" \
  -H "Authorization: Bearer {your_access_token}"

By Building Reference

curl -X GET "https://api-client.covage.com/api/v4/eligibility/site/?building_ref=IMB/31555/X/00RV" \
  -H "Authorization: Bearer {your_access_token}"

Or Both

curl -X GET "https://api-client.covage.com/api/v4/eligibility/site/?building_ref=IMB/31555/X/00RV&x=1.091455&y=49.4744077" \
  -H "Authorization: Bearer {your_access_token}"

Response:

{
  "id": "KHg6MS4wOTE0NTU7eTo0OS40NzQ0MDc3O2I6SU1CLzMxNTU1L1gvMDBSVik=",
  "building_ref": "IMB/31555/X/00RV",
  "location": {
    "x": 1.091455,
    "y": 49.4744077
  }
}

The id field in the response corresponds to the eligibility_id to use for the eligibility request.

Step 2: Create an Eligibility Request

Submit an eligibility request for one or more sites with the desired offer families.

Synchronous vs Asynchronous Mode

The API offers two modes for creating an eligibility request:

Synchronous mode (recommended for machine-to-machine): POST /api/v1/product_offering_qualification/sync/
The response directly contains the eligibility results.
Rate limit: 1 request per second
Asynchronous mode: POST /api/v1/product_offering_qualification/
The request is created and you must then consult Step 3 to retrieve the results once processing is complete.
Rate limit: 10 requests per minute

Synchronous Mode (Recommended)

Endpoint: POST /api/v1/product_offering_qualification/sync/

Rate Limit

Maximum 1 request per second

curl -X POST "https://api-client.covage.com/api/v1/product_offering_qualification/sync/" \
  -H "Authorization: Bearer {your_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "1234",
    "project_id": "5678",
    "product_offering_qualification_items": [
      {
        "offer_families": ["BPEA", "BPE"],
        "eligibility_id": "KHg6MS4wOTE0NTU7eTo0OS40NzQ0MDc3O2I6SU1CLzMxNTU1L1gvMDBSVik=",
        "address": {
          "label": "4bis Rue Andrei Sakharov 76130 Mont-Saint-Aignan",
          "street_ext": "B",
          "street_nr": "4",
          "city": {
            "city_id": "76451",
            "insee_code": "76451",
            "city_name": "MONT ST AIGNAN",
            "post_code": "76130"
          },
          "street": {
            "street_id": "76451055R",
            "street_name": "Rue Andrei Sakharov"
          }
        }
      }
    ]
  }'

Parameters:

Parameter	Type	Description	Required
external_id	string	Customer reference for the request	No
project_id	string	Project identifier	No
product_offering_qualification_items	array	List of sites to test	Yes
↳ eligibility_id	string	Eligibility identifier	Yes
↳ offer_families	array	List of offer families (BPEA, BPE, etc.)	Yes
↳ address	object	Complete site address	No

Immediate Response:

The API directly returns the eligibility results:

{
  "id": "c777a051-45ca-463c-b12d-48136bce5598",
  "creation_date": "2025-12-15T11:39:42.035+01:00",
  "external_id": "1234",
  "effective_qualification_date": null,
  "href": "",
  "state": "done.ready",
  "state_change": [
    {
      "change_reason": "",
      "change_date": "2025-12-15T11:39:42.037+01:00",
      "state": "acknowledged"
    },
    {
      "change_reason": "",
      "change_date": "2025-12-15T11:39:42.254+01:00",
      "state": "in_progress.elig"
    },
    {
      "change_reason": "",
      "change_date": "2025-12-15T11:39:42.663+01:00",
      "state": "in_progress.offer"
    },
    {
      "change_reason": "",
      "change_date": "2025-12-15T11:39:45.719+01:00",
      "state": "done.ready"
    }
  ],
  "product_offering_qualification_items": [
    {
      "id": "7ee14cbd-aecd-4f7f-8843-37b622f3b5f1",
      "user": {
        "email": "admin-covage@covage.com",
        "first_name": "Admin",
        "last_name": "Covage"
      },
      "density": "TRESDENSE",
      "offer_families": [
        "BPE",
        "BPEA"
      ],
      "zone_bpe": 1,
      "zone_bpea": 1,
      "bandwidth_max": 10000.0,
      "place": {
        "location": {
          "x": 1.091455,
          "y": 49.4744077
        },
        "building_ref": "IMB/31555/X/00RV",
        "eligibility_id": "KHg6MS4wOTE0NTU7eTo0OS40NzQ0MDc3O2I6SU1CLzMxNTU1L1gvMDBSVik="
      },
      "address": {
        "label": "4bis Rue Andrei Sakharov 76130 Mont-Saint-Aignan",
        "street_ext": "B",
        "street_nr": "4",
        "city": {
          "city_id": "76451",
          "insee_code": "76451",
          "city_name": "MONT ST AIGNAN",
          "post_code": "76130"
        },
        "street": {
          "street_id": "76451055R",
          "street_name": "Rue Andrei Sakharov"
        }
      },
      "guaranteed_until_date": null,
      "state": "done.ready",
      "state_change": [
        {
          "change_reason": "",
          "change_date": "2025-12-15T11:39:42.051+01:00",
          "state": "acknowledged"
        },
        {
          "change_reason": "",
          "change_date": "2025-12-15T11:39:42.269+01:00",
          "state": "in_progress.elig"
        },
        {
          "change_reason": "",
          "change_date": "2025-12-15T11:39:42.650+01:00",
          "state": "in_progress.offer"
        },
        {
          "change_reason": "",
          "change_date": "2025-12-15T11:39:45.705+01:00",
          "state": "done.ready"
        }
      ],
      "product_offering_qualification_id": null,
      "products_offering": [
        {
          "product_id": "1765",
          "name": "BPEA 100M _Zone très dense_12 mois",
          "description": "BPEA 100M _Zone très dense",
          "bandwidth": "100M",
          "bandwidth_max": 100.0,
          "bandwidth_guarantee": 100.0,
          "commitment": "12MOIS",
          "offer_technology": "FIBDE",
          "offer_family": "BPEA",
          "tarif_zone": "TRESDENSE",
          "price": null,
          "far": null,
          "fas": null,
          "on_quotation": false
        },
        {
          "product_id": "1766",
          "name": "BPEA 200M _Zone très dense_24 mois",
          "description": "BPEA 200M _Zone très dense",
          "bandwidth": "200M",
          "bandwidth_max": 200.0,
          "bandwidth_guarantee": 200.0,
          "commitment": "24MOIS",
          "offer_technology": "FIBDE",
          "offer_family": "BPEA",
          "tarif_zone": "TRESDENSE",
          "price": null,
          "far": null,
          "fas": null,
          "on_quotation": false
        },
        {
          "product_id": "1680",
          "name": "BPE 100M _Zone très dense_24 mois",
          "description": "BPE 100M _Zone très dense",
          "bandwidth": "100M",
          "bandwidth_max": 100.0,
          "bandwidth_guarantee": 100.0,
          "commitment": "24MOIS",
          "offer_technology": "FIBDE",
          "offer_family": "BPE",
          "tarif_zone": "TRESDENSE",
          "price": null,
          "far": null,
          "fas": null,
          "on_quotation": false
        },
        {
          "product_id": "1681",
          "name": "BPE 1G _Zone très dense_36 mois",
          "description": "BPE 1G _Zone très dense",
          "bandwidth": "1G",
          "bandwidth_max": 1000.0,
          "bandwidth_guarantee": 1000.0,
          "commitment": "36MOIS",
          "offer_technology": "FIBDE",
          "offer_family": "BPE",
          "tarif_zone": "TRESDENSE",
          "price": null,
          "far": null,
          "fas": null,
          "on_quotation": false
        }
      ]
    }
  ]
}

Status Table:

Status	Phase	Description
`acknowledged`	Initial	Eligibility request received and acknowledged
`in_progress.elig`	Processing	Eligibility verification in progress
`in_progress.offer`	Processing	Searching for available offers
`done.ready`	Final	Eligibility validated with available offers and pricing
`done.unable_to_provide`	Final	Site not eligible or requires quotation
`terminated_with_error`	Error	Error during data validation

Asynchronous Mode

If you use asynchronous mode, the request is created but processing happens in the background.

Endpoint: POST /api/v1/product_offering_qualification/

Rate Limit

Maximum 10 requests per minute

curl -X POST "https://api-client.covage.com/api/v1/product_offering_qualification/" \
  -H "Authorization: Bearer {your_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "1234",
    "product_offering_qualification_items": [
      {
        "offer_families": ["BPEA", "BPE"],
        "eligibility_id": "KHg6MS4wOTE0NTU7eTo0OS40NzQ0MDc3O2I6SU1CLzMxNTU1L1gvMDBSVik=",
        "address": {
          "label": "4bis Rue Andrei Sakharov 76130 Mont-Saint-Aignan",
          "street_ext": "B",
          "street_nr": "4",
          "city": {
            "city_id": "76451",
            "insee_code": "76451",
            "city_name": "MONT ST AIGNAN",
            "post_code": "76130"
          },
          "street": {
            "street_id": "76451055R",
            "street_name": "Rue Andrei Sakharov"
          }
        }
      }
    ]
  }'

Initial Response:

The response contains the created request ID, but not yet the results:

{
  "id": "c777a051-45ca-463c-b12d-48136bce5598",
  "creation_date": "2025-12-15T11:39:42.035+01:00",
  "external_id": "1234",
  "project_id": "",
  "state": "acknowledged",
  "product_offering_qualification_items": [
    {
      "id": "7ee14cbd-aecd-4f7f-8843-37b622f3b5f1",
    }
  ]
}

You must then use Step 3 to retrieve the results once processing is complete (done.ready state).

Step 3: Consult Eligibility Results

You can consult your eligibility requests at any time. This step is mandatory in asynchronous mode to retrieve results.

List All Eligibilities

Endpoint: GET /api/v1/product_offering_qualification/

curl -X GET "https://api-client.covage.com/api/v1/product_offering_qualification/" \
  -H "Authorization: Bearer {your_access_token}"

Retrieve a Specific Eligibility

Endpoint: GET /api/v1/product_offering_qualification/{id}/

curl -X GET "https://api-client.covage.com/api/v1/product_offering_qualification/21675c4c-ae32-4587-bd66-cc66b188ddf0/" \
  -H "Authorization: Bearer {your_access_token}"

Consult Eligibility Item Details

Endpoint: GET /api/v1/product_offering_qualification_item/{id}/

curl -X GET "https://api-client.covage.com/api/v1/product_offering_qualification_item/d5a4a9aa-ba2c-4f53-95c7-0c1ce6f6e7fa/" \
  -H "Authorization: Bearer {your_access_token}"

List All Eligibility Items

Endpoint: GET /api/v1/product_offering_qualification_item/

curl -X GET "https://api-client.covage.com/api/v1/product_offering_qualification_item/" \
  -H "Authorization: Bearer {your_access_token}"

Next Steps

Now that you know how to authenticate and perform an eligibility check, you can:

📋 Create quotes: Transform an eligibility into a commercial quote
🛒 Place orders: Order an eligible product
📊 Consult your orders: Track the progress of your orders

Consult the complete API documentation to explore all available features.