2-Legged OAuth flow step by step

Before starting
API URL endpoints
application-only Authentication
Access protected resources using OAuth access token
Misuse of access token
List of errors
Sample code

Before starting

In order to call our APIs, you will need credentials for your client application: they are used by the back-end platform to identify your client application and allow it to make calls to the APIs. You receive these credentials when you register your client application on the Orange Developer portal.

At the end of the registration process, you are provided with:

• a client_id: a unique ID provided by the Orange back-end server to identify your client application,
• a client_secret: is a secret known only to the application and the authorization server. It is used to authenticate your client application,

The client_id and client_secret are used in the ‘Basic’ HTTP Authentication scheme (RFC 7617) to compute the value of the Authorization HTTP header.
Its value is composed of the keyword “Basic”, followed by a space and the base64 encoding of the concatenation of your client_id, “:” and your client_secret.

In Javascript, the authorization_header will look something like:

authorization_header = Basic + btoa(client_id + ":" + client_secret)

Our developer dashboard provides directly this information.

WARNING: OAuth 2.0 authorization protocol requires the use of HTTPS for communications between the client and Orange Authorization Server due to the exchange of sensitive data (for instance, app’s credentials – i.e. client_id, client_secret, access token).

API URL endpoints

On ORANGE DEVELOPER, API access are protected using OAuth 2.0 protocols: when requesting an API on its consumption URL endpoint, you’ll need to present a valid OAuth 2.0 access token.

On ORANGE DEVELOPER, these tokens are to be negotiated on a specific /oauth resource path (see below) on the same URL (FQDN) of the API you want to access.

WARNING: in the following paragraphs, you’ll find some real-life curl requests, highlighting examples of OAuth 2.0 token negotiation for APIs published on the api.orange.com FQDN.

DO NOT TAKE THESE EXAMPLES FOR GRANTED AS YOUR PARTICULAR API MAY BE PUBLISHED ON A DIFFERENT FQDN

RATHER, CHECK YOUR SPECIFIC API OFFER DOCUMENTATION SECTION TO LOOK FOR THE PROPER FQDN TO BE USED IN YOUR CASE.

Below is the list of possible API URL FQDNs on ORANGE DEVELOPER.

(*): specific FQDNs for some APIs provided by Orange Business Services (OBS)

application-only Authentication (aka 2-Legged OAuth)

Orange offers client applications the ability to issue authenticated requests to our API on behalf of the client application itself (as opposed to on behalf of a specific end-user). Orange Authorization server’s implementation is based on the Client Credentials Grant flow of the OAuth 2.0 specification.

The client_credentials grant type is used when a client application needs to get an access token for its own account (using client_id/client_secret credentials), outside the context of any specific user.

Discovery mechanism

The discovery endpoint /oauth/v3/.well-known/oauth-authorization-server provides all necessary information your application will need to manage access_token (token endpoint, supported authentication methods for token endpoint, etc.).

Example on the api.orange.com FQDN :

GET https://api.orange.com/oauth/v3/.well-known/oauth-authorization-server HTTP/1.1
Host: api.orange.com
{
  "issuer": "https://api.orange.com/oauth/v3",
  "jwks_uri": "https://api.orange.com/oauth/v3/jwks",
  "token_endpoint": "https://api.orange.com/oauth/v3/token",
  "grant_types_supported": ["client_credentials"],
  "token_endpoint_auth_methods_supported": ["client_secret_post","client_secret_basic"],
  "token_endpoint_auth_signing_alg_values_supported": ["RS256","ES384"],
  "introspection_endpoint": "https://api.orange.com/oauth/v3/introspect",
  "introspection_endpoint_auth_methods_supported":["client_secret_post","client_secret_basic"],
  "introspection_endpoint_auth_signing_alg_values_supported": ["RS256","ES384"]
}

Get OAuth access token

WARNING: Token requests are limited to 50 requests per minute, when the rate limit is exceeded you will receive a 429 error.

WARNING: Header Accept: application/json is now required, when it’s omitted you will receive an error 406 error.

WARNING: Header Authorization is now forbidden when providing client_id/client_secret in the body, you will receive an error 400 error Duplicate credentials.

The access_token is mandatory for API calls to protected resources. To get this token, a POST request must be sent to the token endpoint by adding the following parameters using the “application/x-www-form-urlencoded” format:

• Authorization (Header) (required): the credentials of your client application (i.e. client_id/client_secret). See Before starting section.
• Accept (Header) (required): the response media types that is/are acceptable by the client. For this token negotiation, Accept header MUST be valued with at least one of the following media type declaration : application/json or */*.
• grant_type (required): the authorization grant type. Fixed: client_credentials.

curl -X POST \
-H "Authorization: {authorization_header}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-d "grant_type=client_credentials" \
https://api.orange.com/oauth/v3/token

As an example:

curl -X POST \
-H "Authorization: Basic NktSSHljksdj7P...Jjndb6UdnlrT2lOaA==" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-d "grant_type=client_credentials" \
https://api.orange.com/oauth/v3/token

Please note that, when you perform POST requests with curl or wget, parameters are specified as application/x-www-form-urlencoded through the use of the -d flag.

a/ If the transaction succeeds

The authorization server issues an access_token and constructs the response by adding the following parameters to the entity-body of the HTTP response with a 200 (OK) status code:

• token_type (required): the type of the token issued. Fixed: Bearer.
• access_token (required): the access token issued by the authorization server, and to be used for your API calls, by setting the header as follows: Authorization: Bearer {access_token}.
• expires_in (required): the lifetime in seconds of the access token.

At the end, you should receive JSON payload similar to:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token_type": "Bearer",
  "access_token": "eyJ2ZXIiOiIxLjAiLCJ0eXAiOiJKV1Q.....ODSHIjf",
  "expires_in": 3600
}

From now, you can use this access_token for all subsequent API calls to protected resources (see Access protected resources using OAuth access token section for more information).

NOTE: The access_token is valid for the duration, in seconds, specified by expires_in. Therefore, you do not need to request a new access token as your client application doesn’t receive an error indicating that your access token expired.

If no other value is specified in the getting started page of the API offer, access_token default lifetime is 60 minutes (3600 seconds).

b/ If the transaction fails

Because you provide invalid credentials for example, you will get an error with JSON payload similar to:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
WWW-Authenticate : Basic realm="Authorization Required"

{
  "error": "invalid_client",
  "error_description": "The requested service needs credentials, but the ones provided were invalid."
}

See List of errors for further details.

Access protected resources using OAuth access token

In order to call our API, the access_token is mandatory. The bearer token must be provided in the request using HTTP Authorization header.

curl -X GET \
-H "Authorization: Bearer {access token}" \
https://api.orange.com/{api}/vM/{resource}

As an example:

curl -X GET \
-H "Authorization: Bearer eyJ2ZXIiOiIxLjAiLCJ0eXAiOiJKV1Q.....ODSHIjf" \
https://api.orange.com/poi/v1/shops?postalCode=35000

If your client application attempts to use an expired or revoked access_token, an invalid token error will be returned.

There are some cases where your client application will no longer gain access to API resources, and get an error back.

Please check the following points:

• You attempt to use an expired or revoked access_token and you get an invalid token error. You will have to request a new access_token (as explained in Get OAuth access token). As an example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
WWW-Authenticate : Basic realm="Authorization Required"

{
  "code": 42,
  "message": "Expired credentials",
  "description": "The requested service needs credentials, and the ones provided were out-of-date."
}

• You removed your subscription to the API so that the capability to generate an access_token is not allowed anymore. As an example:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "code": 50,
  "message": "Access Denied",
  "description": "The application that makes the request is not authorized to access this endpoint (ex: not a subscribed service)."
}

• ORANGE DEVELOPER managers have suspended your access (as a consequence of the non-fulfilment of conditions of use for example).

Misuse of access token

Please be aware that a great number of calls for token could have side effects and impact other developers.
We may use protection mechanisms such as limiting token requests. Unfortunately in exceptional cases we can also block your API usage (your application, your account or even your IP) for security reasons.

Please adjust your client application code to use access tokens correctly. One token is valid 1 hour so there is no need to make more token requests to use our products. Mostly do not generate a new token for every functional call.
If you get errors, follow the error description available in the response

List of errors

Below a list of errors (non exhaustive) that your client application can get when calling the token endpoint of the Orange Authorization Server .

The following list of errors fully comply with OAuth 2.0 specification.

As an example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
   "error": "invalid_grant",
   "error_description": "The parameter grant_type is not valid."
}

References

• [OAUTH] Hardt, D., “The OAuth 2.0 Authorization Framework” RFC 6749, October 2012.
• [JSON] “Introducing JSON”

Sample code

You could find some sample code available.

• NodeJS sample client with retry when token expire
• Other sample on oauth.net