Authorization

POST /oauth/exchange

Requires authentication with user access token.

Get a one-time authentication code for the current user. This code can be given to another client, who may use it to request an access token for the same user.

This normally comes into play when you've got:

  • an app client on a mobile device
  • a backend system on a server

The server needs to communicate with SPiD on behalf of the user, but the user authenticates on the app, not the server.

Because of the security implications of having the app share its tokens or the logged in user data with the backend server directly, the app must ask SPiD for a one-time code corresponding to the authenticated user. After retrieving the exchange code, the app may share this code with the backend, which then authenticates directly with SPiD with the code and gets its own user access token - thus keeping a high level of security and giving both apps and backends full access to user data and the SPiD APIs.

Please note:

  • Both clients must belong to the same merchant.
  • The code expires after 30 seconds.

Example of an authentication sequence between a native device app and its Backend API:

Exchange type: session

The process described above allows your backend to communicate on behalf of a user logged into the device. You might also need to generate a session for the user in a webview layer of a native mobile application. You do that with this endpoint as well, setting the type to session.

Example flow:

Help us improve

Did you spot an error? Or maybe you just have a suggestion for how we can improve? Leave us a comment.

Request

POST /api/2/oauth/exchange

clientId

required

The ID of a client belonging to the same merchant as the calling client.

type

required

The type of exchange, either code or session.

redirectUri

optional

Used with type session. The redirect URI must be a registered redirectUri, otherwise the request will be rejected.

Example request

cURL
Minimal example
curl https://login.schibsted.com/api/2/oauth/exchange \
   -X POST \
   -d "oauth_token=[access token]" \
   -d "clientId=4321abc00000000000000000" \
   -d "type=code"
With all parameters
curl https://login.schibsted.com/api/2/oauth/exchange \
   -X POST \
   -d "oauth_token=[access token]" \
   -d "clientId=4321abc00000000000000000" \
   -d "type=code" \
   -d "redirectUri=http://somewhere.com/else/"
Java
Minimal example
Map<String, String> params = new HashMap<>() {{
    put("clientId", "4321abc00000000000000000");,
    put("type", "code");
}};

SpidOAuthToken token = spidClient.getUserToken(code);
String responseJSON = spidClient.
    POST(token, "/oauth/exchange", params).
    getResponseBody();
With all parameters
Map<String, String> params = new HashMap<>() {{
    put("clientId", "4321abc00000000000000000");,
    put("type", "code");,
    put("redirectUri", "http://somewhere.com/else/");
}};

SpidOAuthToken token = spidClient.getUserToken(code);
String responseJSON = spidClient.
    POST(token, "/oauth/exchange", params).
    getResponseBody();

This example is an excerpt, see a full example

PHP
Minimal example
<?php
$params = array(
    "clientId" => "4321abc00000000000000000",
    "type" => "code"
);

$client->auth();
echo var_dump($client->api("/oauth/exchange", "POST", $params));
With all parameters
<?php
$params = array(
    "clientId" => "4321abc00000000000000000",
    "type" => "code",
    "redirectUri" => "http://somewhere.com/else/"
);

$client->auth();
echo var_dump($client->api("/oauth/exchange", "POST", $params));

This example is an excerpt, see a full example

Clojure
Minimal example
(ns example
  (:require [spid-client-clojure.core :as spid]))

(let [client (spid/create-client "[client-id]" "[secret]")
      token (spid/create-user-token client "[code]")]
  (spid/POST client token "/oauth/exchange" {"clientId" "4321abc00000000000000000"
                                             "type" "code"}))
With all parameters
(ns example
  (:require [spid-client-clojure.core :as spid]))

(let [client (spid/create-client "[client-id]" "[secret]")
      token (spid/create-user-token client "[code]")]
  (spid/POST client token "/oauth/exchange" {"clientId" "4321abc00000000000000000"
                                             "type" "code"
                                             "redirectUri" "http://somewhere.com/else/"}))

Response

This endpoint supports the JSON response format.

Success: 200 OK

OAuth exchange object

code

string

An OAuth authentication code. Expires after 30 seconds.

The check mark indicates that the field always contains a valid non-empty value.

Failure cases

Some HTTP response codes are used for multiple error situations. There is no consistent way to tell these apart, but the error object will contain a textual explanation of the reason for the error. For explanation on OAuth related failures and errors see OAuth authentication failures.

  • 400 Bad Request Required client ID missing
  • 400 Bad Request Type session: Missing redirect URI
  • 400 Bad Request Type code: Client to exchange token with is missing a default redirect
  • 400 Bad Request Request must contain a valid exchange type
  • 401 Unauthorized You don't have administration rights for this client.
  • 401 Unauthorized Your client doesn't have administration rights for this client.
  • 403 Forbidden Client is not authorized to access this API endpoint. Contact SPiD to request access.
  • 403 Forbidden Requesting IP is not whitelisted
  • 403 Forbidden Provided client ID does not belong to the current merchant
  • 403 Forbidden Access token rejected
  • 404 Not Found Unknown client ID
  • 404 Not Found Client ID mismatch. The client making the request is no the owner of this resource, and does not have administrative privileges for it.
  • 420 Request Ratelimit exceeded

Sample response

JSON
{"code": "7dac116e0745967464babcefbc56f5f364bac122"}

Comments/feedback

Do you have questions, or just want to contribute some newly gained insight? Want to share an example? Please leave a comment. SPiD reads and responds to every question. Additionally, your experience can help others using SPiD, and it can help us continuously improve our documentation.