.wpb_animate_when_almost_visible { opacity: 1; }

2-Legged OAuth2.0 proxy V3

Before starting
Application-Only Authentication
Access protected resources using OAuth access token
List of errors
Sample code

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: 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 to specify the authorization_header in basic authentication method, it’s also possible to use post parameters if needed.
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, 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.

Discovery mechanism

The discovery endpoint provides all necessary information your application will need to manage access_token (token endpoint, supported authentication methods for token endpoint, etc.).

GET /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: Header Accept: application/json is now required, when it’s omitted you will receive an error 406 error.

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 content type accept in reply. Fixed: application/json.
  • 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": "i6m2iIcY0SodWSe...L3ojAXXrH",
"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.

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 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
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).

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.

HTTP Status Error (mandatory) Error description (optional) Possible fixes
400 invalid_grant The parameter grant_type is not valid. Check that the ‘grant_type’ parameter is well set with ‘client_credentials’ value
400 invalid_request The URI does not support the requested method. Check that you use the right HTTP method (GET, POST, PUT…)
400 invalid_request The requested URI or the requested resource does not exist. Check if URI and endpoint are valid
400 invalid_request Ambigous credentials. Provide only one credential, Authorization in header OR client_id/client_secret in body
400 invalid_request Missing token parameter in body. Check if grant_type and client_id/client_secret (if needed) are in body
400 invalid_request Missing grant_type parameter. Check that the ‘grant_type’ parameter is present
400 unauthorized_client The application that makes the request is not authorized to access this endpoint (ex: not a subscribed service). Check that the status of your subscription to the API offer (must be ‘Approved’)
401 invalid_client The requested service needs credentials, but none were provided. Check if Authorization request header is set with Bearer token. E.g. Authorization: Bearer VOZG7/..//aJPA
401 invalid_client The requested service needs credentials, but the ones provided were invalid. Check if Authorization request header is set with the right Bearer token. E.g. Authorization: Bearer VOZG7/..//aJPA
401 invalid_client Unable to decode Basic authorization. Check that authorization header is base64 encoded as explained in Introduction
403 unauthorized_client The requested service needs credentials, but the ones provided were not approved. Check that the status of your subscription to the API offer (must be ‘Approved’)
403 invalid_request Client certificate fingerprint is not matching with those registered for your application. Check that you use the right client certificate.
403 invalid_request TLS 2 ways endpoint (i.e https://api-ma.orange.com/) must be used by your application. Make your token request to https://api-ma.orange.com/oauth/v3/token instead of https://api.orange.com/oauth/v3/token
404 not_found The requested URI does not exist. Check that the target endpoint exist
406 invalid_request Application must accept application/json response. Check that your request include Accept: application/json in the header
413 invalid_request Request-Body too long.
415 invalid_request Unsupported media type, Content-Type header must be application/x-www-form-urlencoded. Check that your request include Content-Type: application/x-www-form-urlencoded in the header
429 too_many_requests The application has made too many calls and has exceeded the global quota limit for this service. Retry your API call after a short delay (in seconds)
429 too_many_requests The application has made too many calls and has exceeded the rate limit for this service. Retry your API call after a short delay (in seconds)
503 server_error The service is temporarily unavailable. Our service is temporarily down, contact support if problem persist

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:
“`json
HTTP/1.1 429 Too Many Requests
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”

Sample code

You could find some sample code available on oauth.net.