2-Legged OAuth

Before starting

In order to call our API, 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 will receive these credentials when you register your client application on the Orange Developer portal.

At the end of this registration process, you will be provided with:

  • a client_id: a unique ID provided by the Orange back-end server to identify your client application,
  • a client_secret: it is used to sign/encrypt the requests and must be shared by the client and server,

The client_id and client_secret are used to specify the authorization_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 exchanges between the client and the Orange Authorization Server due to sensitive data (for instance, app's credentials - i.e. client_id, client_secret, ID token, access token).

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.

Get OAuth access token

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.
  • grant_type (required): the authorization grant type. Fixed: client_credentials.
curl -X POST \
-H "Authorization: {authorization_header}" \
-d "grant_type=client_credentials" \
https://api.orange.com/oauth/v2/token

As an example:

curl -X POST \
-H "Authorization: Basic NktSSHljksdj7P...Jjndb6UdnlrT2lOaA==" \
-d "grant_type=client_credentials" \
https://api.orange.com/oauth/v2/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": "i6m2iIcY0SodWSe...L3ojAXXrH",
  "expires_in": "7776000"
}

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.

At the present time, access_token have a lifetime of about 90 days.

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
{
  "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 i6m2iIcY0SodWSe...L3ojAXXrH" \
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 Step 1). As an example:
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "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 Partner managers have suspended your access (as a consequence of the non-fulfilment of conditions of use for example).

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. See RFC6749 for further details.

HTTP StatusError (mandatory)Error description (optional)
400invalid_grantThe parameter grant_type is not valid.
400invalid_requestThe URI does not support the requested method.
400invalid_requestThe requested URI or the requested resource does not exist.
400invalid_requestOne or more required query-string parameters are missing.
400unauthorized_clientThe application that makes the request is not authorized to access this endpoint (ex: not a subscribed service).
401invalid_clientThe requested service needs credentials, but none were provided.
401invalid_clientThe requested service needs credentials, but the ones provided were invalid.
401invalid_clientThe requested service needs credentials, and the ones provided were out-of-date.

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."
}

Common errors

Additional errors may occur when requesting our APIs. For instance, when the rate limit defined for an API is exceeded.

In that case, you should receive JSON payload similar to:

As an example:

HTTP/1.1 403 Forbidden
Content-Type: application/json
{
  "code": 53,
  "message": "Too Many Requests",
  "description": "The application has made too many calls and has exceeded the rate limit for this service."
}

See API Reference sections for the full list of common errors.

References

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