Identity Delegation

The purpose of this specification is to define a method by which one app is able to verifiably prove to another application that it has access to a specific user’s account without sharing any secret credentials.


Unless otherwise defined here, terms should have the same approximate usage as the OAuth 2.0 standard.

  • delegate client: The client to which the identity delegation is made (e.g., a photo hosting service)
  • authorized client: The client wishing to make a request to the delegate client (e.g., an mobile client application)


Intentionally not addressed in this document are the following:

  • Authorization of delegate client to make requests to the request server on behalf of the resource owner
  • Discovery of delegate client client_id
  • Discovery of user identity endpoints
  • Format of user identity endpoint


  1. The authorized client completes an OAuth authorization flow and obtains an access token from the resource server. This is outside the scope of this document.

  2. The authorized client makes an authenticated POST request to the resource server OAuth token endpoint:

     POST /oauth/access_token HTTP/1.1
     Authorization: Bearer [access_token]
     Content-Length: 59
     Content-Type: application/x-www-form-urlencoded
     grant_type=delegate&delegate_client_id=[delegate client_id]

    which returns in the body of the reply:

     {"delegate_token": "[delegate token]"}

    For, the OAuth token endpoint is:


    to see more complete examples.

    curl -X POST -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=delegate" -d "delegate_client_id=[your client_id]" \
  3. The authorized client makes a request to the delegate client with two additional headers, Identity-Delegate-Token and Identity-Delegate-Endpoint:

     POST /protected/resource HTTP/1.1
     Identity-Delegate-Token: [delegate_token]
     Content-Length: 100
     Content-Type: application/x-www-form-urlencoded

    The Authorization header is purposefully not used, as another mechanism may be in place for authentication.

    The delegate token and delegate endpoint may also be sent as delegate_token and delegate_endpoint in the query string or POST body.


    to see more complete examples.

    curl -X POST -H "Identity-Delegate-Token: [delegate_token from previous step]" \
     -H "Identity-Delegate-Endpoint:" -H "Content-Type: application/x-www-form-urlencoded" \
     -d "do_some_stuff=1" -d "fo_reals=1" ""
  4. The delegate client identifies the resource server ( by using the Identity-Delegate-Endpoint header and makes a request to that endpoint with the Authorization header set.

    The query string parameters delegate_token, client_id and client_secret may be used in place of HTTP headers if desired.

     GET /token HTTP/1.1
     Authorization: Basic [base64(client_id + ":" + client_secret)]
     Identity-Delegate-Token: [delegate_token]

    which returns in the body of the reply:

         "data": {
             "app": {
                 "client_id": "udxGzAVBdXwGtkHmvswR5MbMEeVnq6n4",
                 "link": "",
                 "name": "Bryan's app for testing"
             "client_id": "udxGzAVBdXwGtkHmvswR5MbMEeVnq6n4",
             "scopes": [
             "user": {
                 "created_at": "2012-07-30T18:57:05Z",
                 "id": "16",
                 "locale": "en_US",
                 "name": "Bryan Berg",
                 "timezone": "America/Los_Angeles",
                 "type": "human",
                 "username": "bryan"
                 [... truncated for the sake of brevity ...],
         "meta": {
             "code": 200
 replies with information about the authorized delegate token. This is the Token object of the authorizing client’s access_token as returned by the Retrieve current Token endpoint.

    The delegate client may verify that the authorized client matches some external authentication scheme and/or list of authorized applications. If the delegate token is not valid for the delegate client’s client_id, this call will return a 401 Unauthorized.

    For, the identity delegation endpoint is:


    to see more complete examples.

    curl -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "Identity-Delegate-Token: [delegate_token]" \


  1. delegate_tokens are valid as long as their associated access_tokens are valid.
  2. The delegate client may cache the return value of the identity delegate endpoint for a short period of time.
  3. Feedback on this flow is welcomed. Please open an issue on the api-spec GitHub repo. Private or security-sensitive commentary can be sent to