Manage using API

Prerequisite to test following examples is to have an API key with permissions:

Path	Methods	ACL
/users/core\.external-user	GET, POST	off
/users/core\.external-user/[0-9a-fA-F]{24}	GET, PATCH, DELETE	off
/users/core\.external-user\.token	GET, POST	off
/users/core\.external-user\.token/[0-9a-fA-F]{24}	GET, DELETE	off

Create

An external user can be a blank document. The system does not require any specific fields. External authentication provider can create an external user document with fields as it likes. Custom schema targeting core.external-user documents can be used to validate documents.

Example external authentication provider creates an external user with attributes name to have presentable user label and source to be able to backtrack original identity. Complete API request is:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-d '
{
  "data": {
    "type": "core.external-user",
    "attributes": {
      "name": "John Smith",
      "source": {
        "provider": "custom-external-provider",
        "identity": "john.smith@some-email-provider.com"
      }
    }
  }
}' \
-X POST https://api.jazer.io/users/core.external-user

The response contains created core.external-user document:

{
  "data": {
    "type": "core.external-user",
    "id": "5a31abd0ac61054ef7fd48ab",
    "attributes": {
      "name": "John Smith",
      "source": {
        "provider": "custom-external-provider",
        "identity": "john.smith@some-email-provider.com"
      }
    },
    "links": {
      "self": "https://api.jazer.io/users/core.external-user/5a31abd0ac61054ef7fd48ab"
    }
  }
}

Type core.external-user with ID 5a31abd0ac61054ef7fd48ab is now a valid authentication identity.

Read

Fetching external user by ID can be achieved using following API request:

curl -H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-X GET https://api.jazer.io/users/core.external-user/<EXTERNAL_USER_ID>

The response contains an external user with the given ID:

{
  "data": {
    "type": "core.external-user",
    "id": "5a31abd0ac61054ef7fd48ab",
    "attributes": {
      "name": "John Smith",
      "source": {
        "provider": "custom-external-provider",
        "identity": "john.smith@some-email-provider.com"
      }
    },
    "links": {
      "self": "https://api.jazer.io/users/core.external-user/5a31abd0ac61054ef7fd48ab"
    }
  }
}

Update

Updating an external user, e.g. changing attribute name, can be done using the following API request:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-d '
{
  "data": {
    "type": "core.external-user",
    "id": "<EXTERNAL_USER_ID>",
    "attributes": {
      "name": "John Alexander Smith"
    }
  }
}' \
-X PATCH https://api.jazer.io/users/core.external-user/<EXTERNAL_USER_ID>

Delete

Deleting an external user is achievable using following API request:

curl -H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-X DELETE https://api.jazer.io/users/core.external-user/<EXTERNAL_USER_ID>

Search

Search is available on the API endpoint /users/core.external-user. All search features are available as in Resources Search. Complete API request to search for external users is:

curl -H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-X GET https://api.jazer.io/users/core.external-user

The response contains core.external-user documents:

{
  "meta": {
    "count": 1
  },
  "data": [
    {
      "type": "core.external-user",
      "id": "5a31abd0ac61054ef7fd48ab",
      "attributes": {
        "name": "John Smith",
        "source": {
          "provider": "custom-external-provider",
          "identity": "john.smith@some-email-provider.com"
        }
      },
      "links": {
        "self": "https://api.jazer.io/users/core.external-user/5a31abd0ac61054ef7fd48ab"
      }
    }
  ],
  "links": {
    "first": "https://api.jazer.io/users/core.external-user?page[offset]=0&page[limit]=20",
    "last": "https://api.jazer.io/users/core.external-user?page[offset]=0&page[limit]=20",
    "prev": null,
    "next": null
  }
}

Token

Create

Creating a token for an external user (i.e. performing a login) is available via document type core.external-user.token. API request must supply Authorization header where value starts with External and ends with base64 encoded value of id:<EXTERNAL_USER_ID>. Example external user ID is 5a31abd0ac61054ef7fd48ab. Base64 encoded value id:5a31abd0ac61054ef7fd48ab is aWQ6NWEzMWFiZDBhYzYxMDU0ZWY3ZmQ0OGFi. Complete API request for an external user with mentioned ID would be:

curl -H 'Accept: application/vnd.api+json' \
-H 'Authorization: External aWQ6NWEzMWFiZDBhYzYxMDU0ZWY3ZmQ0OGFi' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-X POST https://api.jazer.io/users/core.external-user.token

The response contains a created token:

{
  "data": {
    "type": "core.external-user.token",
    "id": "5a31b287ac61054ef7fd48dd",
    "attributes": {
      "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6eyJ0eXBlIjoiY29yZS5leHRlcm5hbC11c2VyLnRva2VuIiwiaWQiOiI1YTMxYjI4N2FjNjEwNTRlZjdmZDQ4ZGQifSwidXNlciI6eyJ0eXBlIjoiY29yZS5leHRlcm5hbC11c2VyIiwiaWQiOiI1YTMxYWJkMGFjNjEwNTRlZjdmZDQ4YWIifSwiaXNzIjoiamF6ZXIiLCJpYXQiOjE1MTMyMDY0MDcsImV4cCI6MTUxNTc5ODQwN30.MEUCIDZIo09JSsRDxyaidF8hP9LG9000k_QnzSXRsCPtun0NAiEA4YwZER84PSykvTISDFLrLPn1K2bBE3hNWau6fQ9bKBQ",
      "created": "2017-12-13T23:06:47.773Z"
    },
    "relationships": {
      "user": {
        "data": {
          "type": "core.external-user",
          "id": "5a31abd0ac61054ef7fd48ab"
        }
      }
    },
    "links": {
      "self": "https://api.jazer.io/users/core.external-user.token/5a31b287ac61054ef7fd48dd"
    }
  }
}

Note

An external user ID is the only information required to have in order to create a token for an external user. Client API key should therefore never have rights to create an external user token. Otherwise, the client could create token directly and bypass external authentication provider verification logic. Only external authentication provider API key should have rights to manage tokens. The provider should always act as a proxy between a client and the system.

Read

A token can be fetched by ID using following API request:

curl -H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-X GET https://api.jazer.io/users/core.external-user.token/<TOKEN_ID>

The response contains a core.external-user.token document with the given ID:

{
  "data": {
    "type": "core.external-user.token",
    "id": "5a31b287ac61054ef7fd48dd",
    "attributes": {
      "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6eyJ0eXBlIjoiY29yZS5leHRlcm5hbC11c2VyLnRva2VuIiwiaWQiOiI1YTMxYjI4N2FjNjEwNTRlZjdmZDQ4ZGQifSwidXNlciI6eyJ0eXBlIjoiY29yZS5leHRlcm5hbC11c2VyIiwiaWQiOiI1YTMxYWJkMGFjNjEwNTRlZjdmZDQ4YWIifSwiaXNzIjoiamF6ZXIiLCJpYXQiOjE1MTMyMDY0MDcsImV4cCI6MTUxNTc5ODQwN30.MEUCIDZIo09JSsRDxyaidF8hP9LG9000k_QnzSXRsCPtun0NAiEA4YwZER84PSykvTISDFLrLPn1K2bBE3hNWau6fQ9bKBQ",
      "created": "2017-12-13T23:06:47.773Z"
    },
    "relationships": {
      "user": {
        "data": {
          "type": "core.external-user",
          "id": "5a31abd0ac61054ef7fd48ab"
        }
      }
    },
    "links": {
      "self": "https://api.jazer.io/users/core.external-user.token/5a31b287ac61054ef7fd48dd"
    }
  }
}

Delete

Deleting a token (i.e. performing a logout) is doable using an API request:

curl -H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-X DELETE https://api.jazer.io/users/core.external-user.token/<TOKEN_ID>

Search

Search is available on the API endpoint /users/core.external-user.token. All search features are available as in Resources Search. Complete API request to search for tokens is:

curl -H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-X GET https://api.jazer.io/users/core.external-user.token

The response contains core.external-user.token documents:

{
  "meta": {
    "count": 1
  },
  "data": [
    {
      "type": "core.external-user.token",
      "id": "5a31b287ac61054ef7fd48dd",
      "attributes": {
        "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6eyJ0eXBlIjoiY29yZS5leHRlcm5hbC11c2VyLnRva2VuIiwiaWQiOiI1YTMxYjI4N2FjNjEwNTRlZjdmZDQ4ZGQifSwidXNlciI6eyJ0eXBlIjoiY29yZS5leHRlcm5hbC11c2VyIiwiaWQiOiI1YTMxYWJkMGFjNjEwNTRlZjdmZDQ4YWIifSwiaXNzIjoiamF6ZXIiLCJpYXQiOjE1MTMyMDY0MDcsImV4cCI6MTUxNTc5ODQwN30.MEUCIDZIo09JSsRDxyaidF8hP9LG9000k_QnzSXRsCPtun0NAiEA4YwZER84PSykvTISDFLrLPn1K2bBE3hNWau6fQ9bKBQ",
        "created": "2017-12-13T23:06:47.773Z"
      },
      "relationships": {
        "user": {
          "data": {
            "type": "core.external-user",
            "id": "5a31abd0ac61054ef7fd48ab"
          }
        }
      },
      "links": {
        "self": "https://api.jazer.io/users/core.external-user.token/5a31b287ac61054ef7fd48dd"
      }
    }
  ],
  "links": {
    "first": "https://api.jazer.io/users/core.external-user.token?page[offset]=0&page[limit]=20",
    "last": "https://api.jazer.io/users/core.external-user.token?page[offset]=0&page[limit]=20",
    "prev": null,
    "next": null
  }
}