Author v1.1

Users

User APIs are defined to provide basic sign up, login, logout and user profile management. User can sign up/register with email, or social network login from Facebook, Google Plus, and Twitter.

User Registration

To register user send POST with following to information to User API root:

  • Type - Email, Facebook, Google Plus, Twitter
  • Email - if type is email provide user's email address
  • Password - if type is email provide user selected password
  • MediaToken - if type is Facebook, Google+ or Twitter provide the access token returned by those APIs.
  • Name - full name of the user

Authorization header is composed of application key concatenated with client secret in the way shown below:

app-key:client-secret

Next the string base64 encoded and passed into Authorization header as a basic authentication:

Authorization: Basic

Refresh tokens

Both registration and login APIs accept optional access_type field in their payload. When access_type is set to offline the API will return refresh token in refresh_token field. If access_type is online or missing no refresh token will be returned.

Sample output with refresh token:

  {
      "expires_in": "240",
      "id": "20cd9793-7f51-11e7-a7fe-f40f2411368f",
      "refresh_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb290IjoiMTA0ZGY1OWEtOTg3NS0xMWU3LWI1MGYtZjQwZjI0MTEzNjhmLGQwNVpqRlh0Y3VwZUlHcExqcFhzNWtMbGxqaHp2eEdNLDIwY2Q5NzkzLTdmNTEtMTFlNy1hN2ZlLWY0MGYyNDExMzY4ZixGYWNlYm9vayxwcm9maWxlIHJvbGVzIn0.dvTRmsLAe7RYBF02r-XLX4P5slREJU_u-KlS6xqk6XPZyepy-s5EJh2eHYy4CXe9urF9xVpoUqAoH5nFxcb-YQ",
      "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJkb21haW4iOiJhcHAxLmNvbWNhc3QuY29tIiwiZXhwIjoxNTA1MzE1ODIxLCJpYXQiOjE1MDUzMDE0MjEsImlkIjoiMTA2NDY3ODk5ODIxMjAxIiwiaXNzIjoiaXJpc2F1dGgiLCJuYW1lIjoiTGlzYSBBbGFjZ2NpZ2NlaGVmIEZhbGxlcmVzY3UiLCJwcm9maWxlX2F2YXRhciI6IiIsInByb2ZpbGVfZW1haWwiOiIiLCJwcm9maWxlX2ZpcnN0X25hbWUiOiJMaXNhIiwicHJvZmlsZV9sYXN0X25hbWUiOiJGYWxsZXJlc2N1IiwicHJvZmlsZV9wcm9maWxlIjp7fSwicHJvZmlsZV9yb2xlcyI6W10sInByb2ZpbGVfdXNlcl9uYW1lIjoiTGlzYSBBbGFjZ2NpZ2NlaGVmIEZhbGxlcmVzY3UiLCJwcm92aWRlcl90eXBlIjoiRmFjZWJvb2siLCJzY29wZXMiOiJjbGllbnQgcmVhZDppZG0gcmVhZHdyaXRlOmVtIHJlYWR3cml0ZTpudG0gaWRzIiwic3ViIjoiMTA2NDY3ODk5ODIxMjAxIiwidHlwZSI6ImNsaWVudCIsInVzZXJfaWQiOiIyMGNkOTc5My03ZjUxLTExZTctYTdmZS1mNDBmMjQxMTM2OGYifQ.idpePkBepJVLtDt5xn0rG_8b6QlSdm54GJoyd6Kwf-rnmgTdDUU8Qzr0VSSdHhwGrB1k-rsCf9L6uRT2aoF4Fg",
      "user_data": {
          "age_range": "",
          "email": "",
          "first_name": "Lisa",
          "gender": "female",
          "last_name": "Fallerescu",
          "middle_name": "Alacgcigcehef",
          "name": "Lisa Alacgcigcehef Fallerescu",
          "picture": ""
      }
  }

NOTE: Every time you login with access_type = offline new refresh token will be given. Auth Manager allows up to 25 refresh tokens per client app (set up in Portal) per user. Once this limit is reached the oldest token will get revoked to make room for the new one.

So suppose you created two client apps using Portal->Create new client key/secret. One for Web and one for Mobile. In this case your mobile app could be set up on 25 user's mobile devices that request refresh token. If the same user would set up 26th mobile device the first mobile device that requested its refresh token would end up with revoked token. But Web app would still be ok because it uses different client key/secret so it has its own 25 entries count.

Note about user_date field

user_data field in v1.1 register/login APIs are provided only to ease conversion from v1 endpoints. In the future release this field will be deprecated and later removed. In order to get, query, update user information use new user profile APIs introduced in v1.1.

User profile and roles

v1.1 APIs have support for user profile and roles. These APIs are described later in this document but register/login APIs have optional field that controls if the user profile and/or roles are included in client JWT claims.

To include profile and/or roles information in client JWT use optional field in register/login APIs called scope. This field can take values profile and/or roles. profile will add user profile information to client JWT and roles will add list of user roles to client JWT claims.

Note that there is a standard list of user profile fields predefined. Those are:

  • user_name
  • first_name
  • last_name
  • email
  • avatar
  • roles
  • profile

All fields above with exception of roles and profile take string values.

roles field accept JSON list of strings to define roles. Values in this list are developer defined and not validated or enforced by Auth Manager.

profile field accepts arbitrary JSON object so the developer can defined and store whatever additional profile information is needed for the application.

Register APIs

Registering via Facebook

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Basic <base_encode64(key:secret)>" \
-d '{"type": "Facebook", "media_token": "EAAIGWvaKMVIBAC02IBmIwUOcme06eLC1GzP0WFjAGZA45FnI2AgjVd2zWH66dz1iQzFKOopQG3yFgc03KqBfkBxKjNfl3DJ5nzZBuf1VZB3eZBaod2GckoxNnTYD1IKTHAwiarseBzY3cfId6UoMsvZCtEUgZBQYLQ4yYM1dFAEEG8OTS3JdBg"}' \
https://aum.iris.comcast.net/v1.1/user

Output: Successful registration

200
{
    "expires_in": "240",
    "id": "20cd9793-7f51-11e7-a7fe-f40f2411368f",
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJkb21haW4iOiJhcHAxLmNvbWNhc3QuY29tIiwiZXhwIjoxNTA1MzE1ODIxLCJpYXQiOjE1MDUzMDE0MjEsImlkIjoiMTA2NDY3ODk5ODIxMjAxIiwiaXNzIjoiaXJpc2F1dGgiLCJuYW1lIjoiTGlzYSBBbGFjZ2NpZ2NlaGVmIEZhbGxlcmVzY3UiLCJwcm9maWxlX2F2YXRhciI6IiIsInByb2ZpbGVfZW1haWwiOiIiLCJwcm9maWxlX2ZpcnN0X25hbWUiOiJMaXNhIiwicHJvZmlsZV9sYXN0X25hbWUiOiJGYWxsZXJlc2N1IiwicHJvZmlsZV9wcm9maWxlIjp7fSwicHJvZmlsZV9yb2xlcyI6W10sInByb2ZpbGVfdXNlcl9uYW1lIjoiTGlzYSBBbGFjZ2NpZ2NlaGVmIEZhbGxlcmVzY3UiLCJwcm92aWRlcl90eXBlIjoiRmFjZWJvb2siLCJzY29wZXMiOiJjbGllbnQgcmVhZDppZG0gcmVhZHdyaXRlOmVtIHJlYWR3cml0ZTpudG0gaWRzIiwic3ViIjoiMTA2NDY3ODk5ODIxMjAxIiwidHlwZSI6ImNsaWVudCIsInVzZXJfaWQiOiIyMGNkOTc5My03ZjUxLTExZTctYTdmZS1mNDBmMjQxMTM2OGYifQ.idpePkBepJVLtDt5xn0rG_8b6QlSdm54GJoyd6Kwf-rnmgTdDUU8Qzr0VSSdHhwGrB1k-rsCf9L6uRT2aoF4Fg",
    "user_data": {
        "age_range": "",
        "email": "",
        "first_name": "Lisa",
        "gender": "female",
        "last_name": "Fallerescu",
        "middle_name": "Alacgcigcehef",
        "name": "Lisa Alacgcigcehef Fallerescu",
        "picture": ""
    }
}

Output: User already registered

401
{"error":{"code":"AUTH_0003","message":"User already exists.  Login instead."}}

Registering via TokenExchange

TokenExchange login/register allows to exchange non Iris RSA256 signed JWT for Iris JWT. In order for this login/register API to work you need to go to Auth Type->Token Exchange Auth menu in Iris Portal and provide required information.

The required fields are public key that Iris Auth Manager can use to validate the signature of JWT. JWT must be RSA256 signed. Currently this is the only algorithm supported. In addition, you must specify the name of the claim in your JWT (the one you send to Iris) that contains unique value by which user can be identified. This field must come from claim in payload section of the JWT and will be used to serve as an unique identifier for user represented by JWT.

Iris Auth Manager will use this unique identifier to differentiate between users in your domain that login with TokenExchange type. Note, that once you settle on the unique identifier you must not change it as this may cause problems with finding existing users. If you need to change it at some point due to some design change please contact Iris team.

Note: Unique identifier entry in portal is case sensitive and must match claim name exactly.

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Basic <base_encode64(key:secret)>" \
-d '{"type": "TokenExchange", "media_token": ""}' \
https://aum.iris.comcast.net/v1.1/user

Output: Successful registration

200
{
    "expires_in": "240",
    "id": "21513ccd-7f51-11e7-a7fe-f40f2411368f",
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJkb21haW4iOiJhcHAxLmNvbWNhc3QuY29tIiwiZXhwIjoxNTA1MzIyNDU0LCJpYXQiOjE1MDUzMDgwNTQsImlkIjoiNTM1OTA2MzgwMTIwMDIyMDE2Q29tY2FzdC5jdXN0IiwiaXNzIjoiaXJpc2F1dGgiLCJwcm9maWxlX2F2YXRhciI6IiIsInByb2ZpbGVfZW1haWwiOiJST0JKU0xJV0FAY29tY2FzdC5uZXQiLCJwcm9maWxlX2ZpcnN0X25hbWUiOiIiLCJwcm9maWxlX2xhc3RfbmFtZSI6IiIsInByb2ZpbGVfcHJvZmlsZSI6e30sInByb2ZpbGVfcm9sZXMiOltdLCJwcm9maWxlX3VzZXJfbmFtZSI6IiIsInByb3ZpZGVyX3R5cGUiOiJDaW1hIiwic2NvcGVzIjoiY2xpZW50IHJlYWQ6aWRtIHJlYWR3cml0ZTplbSByZWFkd3JpdGU6bnRtIGlkcyIsInN1YiI6IjUzNTkwNjM4MDEyMDAyMjAxNkNvbWNhc3QuY3VzdCIsInR5cGUiOiJjbGllbnQiLCJ1c2VyX2lkIjoiMjE1MTNjY2QtN2Y1MS0xMWU3LWE3ZmUtZjQwZjI0MTEzNjhmIn0.-5ohUL10L-W2IpG-3a7lp56paUhKLLw8YIK2PQMm4ufW9M1Be_r1xls7n9WrfZ_uD5mX4EFFlssmPTx61PNSzA"
}

Output: User already registered

401
{"error":{"code":"AUTH_0003","message":"User already exists.  Login instead."}}

Registering via Mercury

In order to use Mercury registration/login you need to first set up credentials and validation URL in Iris Portal.

curl -X POST -H "Content-Type: application/json"
-H "Authorization: Basic <base_encode64(key:secret)>"
-d '{"type": "Mercury", "media_token": "<Mercury token>"}'
https://aum.iris.comcast.net/v1.1/user

Output: Successful registration

200
{
    "expires_in": "240",
    "id": "21513ccd-7f51-11e7-a7fe-f40f2411368f",
    "token": ""
}

Output: User already registered

401
{"error":{"code":"AUTH_0003","message":"User already exists.  Login instead."}}

Registering via CIMA

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Basic <base_encode64(key:secret)>" \
-d '{"type": "Cima", "media_token": "EAAIGWvaKMVIBAC02IBmIwUOcme06eLC1GzP0WFjAGZA45FnI2AgjVd2zWH66dz1iQzFKOopQG3yFgc03KqBfkBxKjNfl3DJ5nzZBuf1VZB3eZBaod2GckoxNnTYD1IKTHAwiarseBzY3cfId6UoMsvZCtEUgZBQYLQ4yYM1dFAEEG8OTS3JdBg"}' \
https://aum.iris.comcast.net/v1.1/user

Output: Successful registration

200
{
    "expires_in": "240",
    "id": "21513ccd-7f51-11e7-a7fe-f40f2411368f",
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJkb21haW4iOiJhcHAxLmNvbWNhc3QuY29tIiwiZXhwIjoxNTA1MzIyNDU0LCJpYXQiOjE1MDUzMDgwNTQsImlkIjoiNTM1OTA2MzgwMTIwMDIyMDE2Q29tY2FzdC5jdXN0IiwiaXNzIjoiaXJpc2F1dGgiLCJwcm9maWxlX2F2YXRhciI6IiIsInByb2ZpbGVfZW1haWwiOiJST0JKU0xJV0FAY29tY2FzdC5uZXQiLCJwcm9maWxlX2ZpcnN0X25hbWUiOiIiLCJwcm9maWxlX2xhc3RfbmFtZSI6IiIsInByb2ZpbGVfcHJvZmlsZSI6e30sInByb2ZpbGVfcm9sZXMiOltdLCJwcm9maWxlX3VzZXJfbmFtZSI6IiIsInByb3ZpZGVyX3R5cGUiOiJDaW1hIiwic2NvcGVzIjoiY2xpZW50IHJlYWQ6aWRtIHJlYWR3cml0ZTplbSByZWFkd3JpdGU6bnRtIGlkcyIsInN1YiI6IjUzNTkwNjM4MDEyMDAyMjAxNkNvbWNhc3QuY3VzdCIsInR5cGUiOiJjbGllbnQiLCJ1c2VyX2lkIjoiMjE1MTNjY2QtN2Y1MS0xMWU3LWE3ZmUtZjQwZjI0MTEzNjhmIn0.-5ohUL10L-W2IpG-3a7lp56paUhKLLw8YIK2PQMm4ufW9M1Be_r1xls7n9WrfZ_uD5mX4EFFlssmPTx61PNSzA",
    "user_data": {
        "cust_guid": "12223435453535656Comcast.cust",
        "email": "someone@comcast.net"
    }
}

Output: User already registered

401
{"error":{"code":"AUTH_0003","message":"User already exists.  Login instead."}}

Registering via Email

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Basic <base_encode64(key:secret)>" \
-d '{"type": "Email", "email": "test20@test.com", "name": "Gucio Gonzalinski", "password": "password"}' \
https://aum.iris.comcast.net/v1.1/user

Output: Successful registration

200
{
    "expires_in": "240",
    "id": "c6cedfae-971f-11e7-a74b-f40f2411368f",
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJkb21haW4iOiJhcHAxLmNvbWNhc3QuY29tIiwiZXhwIjoxNTA1MzIyNjU4LCJpYXQiOjE1MDUzMDgyNTgsImlkIjoidGVzdDIwQHRlc3QuY29tIiwiaXNzIjoiaXJpc2F1dGgiLCJuYW1lIjoiR3VjaW8gR29uemFsaW5za2kiLCJwcm9maWxlX2F2YXRhciI6IiIsInByb2ZpbGVfZW1haWwiOiJ0ZXN0MjBAdGVzdC5jb20iLCJwcm9maWxlX2ZpcnN0X25hbWUiOiIiLCJwcm9maWxlX2xhc3RfbmFtZSI6IiIsInByb2ZpbGVfcHJvZmlsZSI6e30sInByb2ZpbGVfcm9sZXMiOltdLCJwcm9maWxlX3VzZXJfbmFtZSI6Ikd1Y2lvIEdvbnphbGluc2tpIiwicHJvdmlkZXJfdHlwZSI6IkVtYWlsIiwic2NvcGVzIjoiY2xpZW50IHJlYWQ6aWRtIHJlYWR3cml0ZTplbSByZWFkd3JpdGU6bnRtIGlkcyIsInN1YiI6InRlc3QyMEB0ZXN0LmNvbSIsInR5cGUiOiJjbGllbnQiLCJ1c2VyX2lkIjoiYzZjZWRmYWUtOTcxZi0xMWU3LWE3NGItZjQwZjI0MTEzNjhmIn0.NwNqnDSsqmDKgOLTeeeruwc7P5WE5LpmqUPR5S9Kqh6eLJ8ZIK64_NJMJ14eJub0wMy4NQse05hm7cwyVT2YPg",
    "user_data": {
        "email": "test20@test.com",
        "name": "Gucio Gonzalinski"
    }
}

Registration of Device

curl -X POST -H "Content-Type: application/json" -H "Authorization: Basic <base_encode64(key:secret)>"
-d '{"type": "Device", "type_id": "1232343534dw"}'
https://aum.iris.comcast.net/v1.1/user

Output: Successful Registration

200
{
    "expires_in": "240",
    "id": "0efcf54c-9888-11e7-b50f-f40f2411368f",
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJkb21haW4iOiJhcHAxLmNvbWNhc3QuY29tIiwiZXhwIjoxNTA1MzIzOTkxLCJpYXQiOjE1MDUzMDk1OTEsImlkIjoiMTIzMjM0MzUzNGR3IiwiaXNzIjoiaXJpc2F1dGgiLCJwcm9maWxlX2F2YXRhciI6IiIsInByb2ZpbGVfZW1haWwiOiIiLCJwcm9maWxlX2ZpcnN0X25hbWUiOiIiLCJwcm9maWxlX2xhc3RfbmFtZSI6IiIsInByb2ZpbGVfcHJvZmlsZSI6e30sInByb2ZpbGVfcm9sZXMiOltdLCJwcm9maWxlX3VzZXJfbmFtZSI6IiIsInByb3ZpZGVyX3R5cGUiOiJEZXZpY2UiLCJzY29wZXMiOiJjbGllbnQgcmVhZDppZG0gcmVhZHdyaXRlOmVtIHJlYWR3cml0ZTpudG0gaWRzIiwic3ViIjoiMTIzMjM0MzUzNGR3IiwidHlwZSI6ImNsaWVudCIsInVzZXJfaWQiOiIwZWZjZjU0Yy05ODg4LTExZTctYjUwZi1mNDBmMjQxMTM2OGYifQ.GCq04ahaiHyhI7c-D7xXFXJ0jWxoYL0utv886GW3EqWsO3r3XgX5gq_tpmvUzb3w7okghH7E-IXxEvj-eKWlZg",
    "user_data": {}
}

Already registered

{"error":{"code":"AUTH_0003","message":"User already exists.  Login instead."}}

Get Information About Current User

To get current user send GET to the user/current API.

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <client JWT>" \
https://aum.iris.comcast.net/v1.1/user/current

Returns status 200 and JSON string with all of the available user information:

{"id":"a211d942-9b9b-11e6-8db1-fa163e7504ec","user_data":{"first_name":"Lisa","gender":"female","last_name":"Fallerescu","middle_name":"Alacgcigcehef","name":"Lisa Alacgcigcehef Fallerescu"}}

Validate User Access Token

This is API is meant to be used by other servers in order to validate received JWT token. With this API other services can use Contact Manager as authentication service for the currently logged in user.

curl -X GET \
-H "Content-Type: application/json" \
-H "Autherization: Basic <base_encode64(key:secret)>" \
https://aum.iris.comcast.net/v1/user/validate?access_token=

Returns status 200 and JSON string with success message:

200
{"message":"Valid token"}

or in case of failure status and JSON string will contain exact description for token validation failure. For example:

401
{"error":{"code":"AUTH_0010","message":"Invalid access token"}}

User Login

To login user the user send POST to login API root with the following values:

  • Type - Email, Facebook, Google +, Twitter
  • Email, password - is type is email
  • Media Token - if type is Facebook, Google +, Twitter

Login via Google Plus

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Basic <base_encode64(key:secret)>" \
-d '{"type": "Google Plus", "media_token": ""}' \
https://aum.iris.comcast.net/v1.1/login

Successful login will return status 200 and JSON with access token:

Example of successful login via Google Plus

200
{
    "expires_in": "240",
    "id": "212802eb-7f51-11e7-a7fe-f40f2411368f",
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJkb21haW4iOiJhcHAxLmNvbWNhc3QuY29tIiwiZXhwIjoxNTA1MzI0ODE3LCJpYXQiOjE1MDUzMTA0MTcsImlkIjoiMTE0MjIxODQ2NTI2MzIwMDIzMzgxIiwiaXNzIjoiaXJpc2F1dGgiLCJuYW1lIjoiUm9iZXJ0IFNsaXdhIiwicHJvZmlsZV9hdmF0YXIiOiJodHRwczovL2xoNC5nb29nbGV1c2VyY29udGVudC5jb20vLU9XUU1VeEJObUNrL0FBQUFBQUFBQUFJL0FBQUFBQUFBQUFBL0FNcDVWVXFabk1jdmhodk1sb0lhR0lQQnpUSzFzUzJzM0Evczk2LWMvcGhvdG8uanBnIiwicHJvZmlsZV9lbWFpbCI6IiIsInByb2ZpbGVfZmlyc3RfbmFtZSI6IiIsInByb2ZpbGVfbGFzdF9uYW1lIjoiIiwicHJvZmlsZV9wcm9maWxlIjp7fSwicHJvZmlsZV9yb2xlcyI6W10sInByb2ZpbGVfdXNlcl9uYW1lIjoiUm9iZXJ0IFNsaXdhIiwicHJvdmlkZXJfdHlwZSI6Ikdvb2dsZSBQbHVzIiwic2NvcGVzIjoiY2xpZW50IHJlYWQ6aWRtIHJlYWR3cml0ZTplbSByZWFkd3JpdGU6bnRtIGlkcyIsInN1YiI6IjExNDIyMTg0NjUyNjMyMDAyMzM4MSIsInR5cGUiOiJjbGllbnQiLCJ1c2VyX2lkIjoiMjEyODAyZWItN2Y1MS0xMWU3LWE3ZmUtZjQwZjI0MTEzNjhmIn0.O_ouEVTbQBrq5xCYb6qqv-8dlR49Xuen8RzZt4hlncVoq2Vw2nUZ44Ta9DNrNvylzsSqGxmvGaimrWEd4Gz9tg",
    "user_data": {
        "email": "",
        "first_name": "",
        "last_name": "",
        "name": "Person Name",
        "picture": "https://lh4.googleusercontent.com/-OWQMUxBNmCk/AAAAAAAAAAI/AAAAAAAAAAA/sdfdfdfs/s96-c/photo.jpg"
    }
}

Login via Email

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Basic <base_encode64(key:secret)>" \
-d '{"type": "Email", "email": "test2@test.com", "password": "password"}' \
https://aum.iris.comcast.net/v1.1/login

Example of successful login via Email

200
{
    "expires_in": "240",
    "id": "c6cedfae-971f-11e7-a74b-f40f2411368f",
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJkb21haW4iOiJhcHAxLmNvbWNhc3QuY29tIiwiZXhwIjoxNTA1MzIyNjU4LCJpYXQiOjE1MDUzMDgyNTgsImlkIjoidGVzdDIwQHRlc3QuY29tIiwiaXNzIjoiaXJpc2F1dGgiLCJuYW1lIjoiR3VjaW8gR29uemFsaW5za2kiLCJwcm9maWxlX2F2YXRhciI6IiIsInByb2ZpbGVfZW1haWwiOiJ0ZXN0MjBAdGVzdC5jb20iLCJwcm9maWxlX2ZpcnN0X25hbWUiOiIiLCJwcm9maWxlX2xhc3RfbmFtZSI6IiIsInByb2ZpbGVfcHJvZmlsZSI6e30sInByb2ZpbGVfcm9sZXMiOltdLCJwcm9maWxlX3VzZXJfbmFtZSI6Ikd1Y2lvIEdvbnphbGluc2tpIiwicHJvdmlkZXJfdHlwZSI6IkVtYWlsIiwic2NvcGVzIjoiY2xpZW50IHJlYWQ6aWRtIHJlYWR3cml0ZTplbSByZWFkd3JpdGU6bnRtIGlkcyIsInN1YiI6InRlc3QyMEB0ZXN0LmNvbSIsInR5cGUiOiJjbGllbnQiLCJ1c2VyX2lkIjoiYzZjZWRmYWUtOTcxZi0xMWU3LWE3NGItZjQwZjI0MTEzNjhmIn0.NwNqnDSsqmDKgOLTeeeruwc7P5WE5LpmqUPR5S9Kqh6eLJ8ZIK64_NJMJ14eJub0wMy4NQse05hm7cwyVT2YPg",
    "user_data": {
        "email": "test20@test.com",
        "name": "Gucio Gonzalinski"
    }
}

Result when incorrect password was provided

{"error":{"message":"Invalid password"}}

Login via TokenExchange token

curl -X POST -H "Content-Type: application/json"
-H "Authorization: Basic <base_encode64(key:secret)>"
-d '{"type": "TokenExchange", "media_token": "RSA256 signed JWT"}'
https://aum.iris.comcast.net/v1.1/login

Example of successful login via TokenExchange

200
{
    "expires_in": "240",
    "id": "21513ccd-7f51-11e7-a7fe-f40f2411368f",
    "idmapping_count": 0,
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJkb21haW4iOiJhcHAxLmNvbWNhc3QuY29tIiwiZXhwIjoxNTA1MzIyNDU0LCJpYXQiOjE1MDUzMDgwNTQsImlkIjoiNTM1OTA2MzgwMTIwMDIyMDE2Q29tY2FzdC5jdXN0IiwiaXNzIjoiaXJpc2F1dGgiLCJwcm9maWxlX2F2YXRhciI6IiIsInByb2ZpbGVfZW1haWwiOiJST0JKU0xJV0FAY29tY2FzdC5uZXQiLCJwcm9maWxlX2ZpcnN0X25hbWUiOiIiLCJwcm9maWxlX2xhc3RfbmFtZSI6IiIsInByb2ZpbGVfcHJvZmlsZSI6e30sInByb2ZpbGVfcm9sZXMiOltdLCJwcm9maWxlX3VzZXJfbmFtZSI6IiIsInByb3ZpZGVyX3R5cGUiOiJDaW1hIiwic2NvcGVzIjoiY2xpZW50IHJlYWQ6aWRtIHJlYWR3cml0ZTplbSByZWFkd3JpdGU6bnRtIGlkcyIsInN1YiI6IjUzNTkwNjM4MDEyMDAyMjAxNkNvbWNhc3QuY3VzdCIsInR5cGUiOiJjbGllbnQiLCJ1c2VyX2lkIjoiMjE1MTNjY2QtN2Y1MS0xMWU3LWE3ZmUtZjQwZjI0MTEzNjhmIn0.-5ohUL10L-W2IpG-3a7lp56paUhKLLw8YIK2PQMm4ufW9M1Be_r1xls7n9WrfZ_uD5mX4EFFlssmPTx61PNSzA"
}

NOTE: idmapping_count field is deprecated and will not be available in the future releases. You should not count on its presence or use its value anymore.

Login via Mercury

In order to use Mercury registration/login you need to first set up credentials and validation URL in Iris Portal.

curl -X POST -H "Content-Type: application/json"
-H "Authorization: Basic <base_encode64(key:secret)>"
-d '{"type": "Mercury", "media_token": "<Mercury token>"}'
https://aum.iris.comcast.net/v1.1/login

Example of successful login via Mercury

200
{
    "expires_in": "240",
    "id": "21513ccd-7f51-11e7-a7fe-f40f2411368f",
    "token": ""
}

Mercury Login type id change

For Mercury login type you can also use API to change Broadsoft ID:

curl -X PUT -H "Content-Type: application/json"
-H "Authorization: Basic <base_encode64(key:secret)>"
-d '{"type": "Mercury", "old_id": "<old Broadsoft ID>", "new_id": "<new Boradsoft ID>"}'
https://aum.iris.comcast.net/v1.1/user/changeid

Successful call with return:

200
{
    "message": "success"
}

Possible errors are:

  • 400 AUTH_0004 Incorrect credentials Verify Basic auth credentials used for call and retry
  • 400 AUTH_0005 Invalid Payload Correct request payload and retry
  • 401 AUTH_0010 Invalid Access token obtain valid token and retry request
  • 500 AUTH_0008 Internal Error Retry request
  • 400 AUTH_0011 Invalid Parameter - missing access token provide access token and retry request
  • 500 AUTH_0010 Internal Error - Invalid database connection etc. Retry request
  • 404 AUTH_0030 Broadsoft ID (old broadsoft id) not found

Login via CIMA token

curl -X POST -H "Content-Type: application/json"
-H "Authorization: Basic <base_encode64(key:secret)>"
-d '{"type": "Cima", "media_token": ""}'
https://aum.iris.comcast.net/v1.1/login

Example of successful login via CIMA

200
{
    "expires_in": "240",
    "id": "21513ccd-7f51-11e7-a7fe-f40f2411368f",
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJkb21haW4iOiJhcHAxLmNvbWNhc3QuY29tIiwiZXhwIjoxNTA1MzIyNDU0LCJpYXQiOjE1MDUzMDgwNTQsImlkIjoiNTM1OTA2MzgwMTIwMDIyMDE2Q29tY2FzdC5jdXN0IiwiaXNzIjoiaXJpc2F1dGgiLCJwcm9maWxlX2F2YXRhciI6IiIsInByb2ZpbGVfZW1haWwiOiJST0JKU0xJV0FAY29tY2FzdC5uZXQiLCJwcm9maWxlX2ZpcnN0X25hbWUiOiIiLCJwcm9maWxlX2xhc3RfbmFtZSI6IiIsInByb2ZpbGVfcHJvZmlsZSI6e30sInByb2ZpbGVfcm9sZXMiOltdLCJwcm9maWxlX3VzZXJfbmFtZSI6IiIsInByb3ZpZGVyX3R5cGUiOiJDaW1hIiwic2NvcGVzIjoiY2xpZW50IHJlYWQ6aWRtIHJlYWR3cml0ZTplbSByZWFkd3JpdGU6bnRtIGlkcyIsInN1YiI6IjUzNTkwNjM4MDEyMDAyMjAxNkNvbWNhc3QuY3VzdCIsInR5cGUiOiJjbGllbnQiLCJ1c2VyX2lkIjoiMjE1MTNjY2QtN2Y1MS0xMWU3LWE3ZmUtZjQwZjI0MTEzNjhmIn0.-5ohUL10L-W2IpG-3a7lp56paUhKLLw8YIK2PQMm4ufW9M1Be_r1xls7n9WrfZ_uD5mX4EFFlssmPTx61PNSzA",
    "user_data": {
        "cust_guid": "12223435453535656Comcast.cust",
        "email": "someone@comcast.net"
    }
}

Login for Device

curl -X POST -H "Content-Type: application/json" -H "Authorization: Basic <base_encode64(key:secret)>"
-d '{"type": "Device", "type_id": "1234567"}'
https://aum.iris.comcast.net/v1.1/login

Example of successful login for device

200
{
    "expires_in": "240",
    "id": "0efcf54c-9888-11e7-b50f-f40f2411368f",
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJkb21haW4iOiJhcHAxLmNvbWNhc3QuY29tIiwiZXhwIjoxNTA1MzIzOTkxLCJpYXQiOjE1MDUzMDk1OTEsImlkIjoiMTIzMjM0MzUzNGR3IiwiaXNzIjoiaXJpc2F1dGgiLCJwcm9maWxlX2F2YXRhciI6IiIsInByb2ZpbGVfZW1haWwiOiIiLCJwcm9maWxlX2ZpcnN0X25hbWUiOiIiLCJwcm9maWxlX2xhc3RfbmFtZSI6IiIsInByb2ZpbGVfcHJvZmlsZSI6e30sInByb2ZpbGVfcm9sZXMiOltdLCJwcm9maWxlX3VzZXJfbmFtZSI6IiIsInByb3ZpZGVyX3R5cGUiOiJEZXZpY2UiLCJzY29wZXMiOiJjbGllbnQgcmVhZDppZG0gcmVhZHdyaXRlOmVtIHJlYWR3cml0ZTpudG0gaWRzIiwic3ViIjoiMTIzMjM0MzUzNGR3IiwidHlwZSI6ImNsaWVudCIsInVzZXJfaWQiOiIwZWZjZjU0Yy05ODg4LTExZTctYjUwZi1mNDBmMjQxMTM2OGYifQ.GCq04ahaiHyhI7c-D7xXFXJ0jWxoYL0utv886GW3EqWsO3r3XgX5gq_tpmvUzb3w7okghH7E-IXxEvj-eKWlZg",
    "user_data": {}
}

curl -X POST -H "Content-Type: application/json"
-H "Authorization: Basic <base_encode64(key:secret)>"
-d '{"type": "Server"}'
https://aum.iris.comcast.net/v1.1/login

Example of successful JWT get for app server to server

200
{
    "expires_in": 129600,
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJkb21haW4iOiJhcHAxLmNvbWNhc3QuY29tIiwiZXhwIjoxNTEzMDg3MDc4LCJpYXQiOjE1MDUzMTEwNzgsImlkIjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJpc3MiOiJpcmlzYXV0aCIsInByb3ZpZGVyX3R5cGUiOiJTZXJ2ZXIiLCJzY29wZXMiOiJjbGllbnQgcmVhZHdyaXRlOmlkbSByZWFkd3JpdGU6ZW0gaWRzIiwic3ViIjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJ0eXBlIjoiU2VydmVyIn0.JcMGxlVMZLFcJmSP2nrRIEZgJkZGoEDadx6qAzVOY3df1wtxReJ1skaSB1sPWY_iGhrPtx0yX26IEXYhWce7ag"
}

Anonymous Login

This API edge allows anonymous login. This means that no user will be created and persisted on the server to identify client who request it. To perform anonymous login POST to the API edge described below. The only parameter is UserID. The information in UserID is only used to encoded it in the JWT access token that will be returned if this call is successful. If you do not need to provide any user identifier simply pass empty string in UserID field.

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Basic <base_encode64(key:secret)>" \
-d '{"user_id": "some user id"}'
https://aum.iris.comcast.net/v1.1/login/anonymous

Result Return valid JWT access token. No user entry is created.

{
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJkb21haW4iOiJhcHAxLmNvbWNhc3QuY29tIiwiZXhwIjoxNTA1MzI1NjM3LCJpYXQiOjE1MDUzMTEyMzcsImlkIjoiZGtqZmRrbGZqbGtkamZrIiwiaXNzIjoiaXJpc2F1dGgiLCJuYW1lIjoiYW5vbnltb3VzIiwicHJvdmlkZXJfdHlwZSI6IkFub255bW91cyIsInNjb3BlcyI6ImNsaWVudCByZWFkOmlkbSByZWFkd3JpdGU6ZW0gcmVhZHdyaXRlOm50bSBpZHMiLCJzdWIiOiJka2pmZGtsZmpsa2RqZmsiLCJ0eXBlIjoiY2xpZW50IiwidXNlcl9pZCI6ImRramZka2xmamxrZGpmayJ9.giwyJBvJWXtzeHsDkR_eMDYTXrCasCTKcf2skjM7Y8PuHwvx1DIVBuvlEiIY5zUU2i6kK21cGG03G3ZJU85BPA"
}

Login with Refresh Token

To login with refresh token use the following API:

curl -X POST -H "Content-Type: application/json"
-H "Authorization: Basic <base_encode64(key:secret)>"
-d '{"refresh_token": "<refresh token>"}'
https://aum.iris.comcast.net/v1.1/token

Successful call:

200
{
    "expires_in": "240",
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiZDA1WmpGWHRjdXBlSUdwTGpwWHM1a0xsbGpoenZ4R00iLCJkb21haW4iOiJhcHAxLmNvbWNhc3QuY29tIiwiZXhwIjoxNTA1NDAxNzY1LCJpYXQiOjE1MDUzODczNjUsImlkIjoidGVzdDIwQHRlc3QuY29tIiwiaXNzIjoiaXJpc2F1dGgiLCJuYW1lIjoiR3VjaW8gR29uemFsaW5za2kiLCJwcm9maWxlX2F2YXRhciI6IiIsInByb2ZpbGVfZW1haWwiOiJ0ZXN0MjBAdGVzdC5jb20iLCJwcm9maWxlX2ZpcnN0X25hbWUiOiIiLCJwcm9maWxlX2xhc3RfbmFtZSI6IiIsInByb2ZpbGVfcHJvZmlsZSI6e30sInByb2ZpbGVfcm9sZXMiOltdLCJwcm9maWxlX3VzZXJfbmFtZSI6Ikd1Y2lvIEdvbnphbGluc2tpIiwicHJvdmlkZXJfdHlwZSI6IkVtYWlsIiwic2NvcGVzIjoiY2xpZW50IHJlYWQ6aWRtIHJlYWR3cml0ZTplbSByZWFkd3JpdGU6bnRtIGlkcyIsInN1YiI6InRlc3QyMEB0ZXN0LmNvbSIsInR5cGUiOiJjbGllbnQiLCJ1c2VyX2lkIjoiYzZjZWRmYWUtOTcxZi0xMWU3LWE3NGItZjQwZjI0MTEzNjhmIn0.JhSRqb02C9M5Zzm6PqBTYoCj2Ub8YcTbKZvfVCWrMlBL3lSgFpkFUeJ1H7P7Y5UeLIqC59wq5U4djttDPdfu9A"
}

When token is invalid or revoked:

401
{
    "error": {
        "code": "AUTH_0012",
        "message": "Refresh token is invalid or revoked"
    }
}

Revoke Refresh Token

Use this API when client wants to revoke refresh token:

curl -X DELETE -H "Content-Type: application/json"
-H "Authorization: Basic <base_encode64(key:secret)>"
-d '{"refresh_token": "<refresh token>"}'
https://aum.iris.comcast.net/v1.1/token

This API always returns success even if the refresh token was already revoked:

200
{
    "message": "Token revoked"
}

User Logout

To logout the user send GET to logout API root with valid access token.

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Iris JWT>" \
https://aum.iris.comcast.net/v1.1/logout

Successful logout will return status 200 and JSON string with success message:

200
{"status":"User logged out"}

Auth Manager Version

This API end point returns Auth Manager version.

curl -X GET -H "Content-Type: application/json"
https://aum.iris.comcast.net/v1.1/version

Sample output:

{"version":"v1.0.13"}

Update User Profile

Update user profile for the given user ID.

This API accepts client or server JWT. If client JWT is passed then userID passed in to the API must match the user ID of the client JWT. That is, client JWT cannot update profiles of other users. Updating profiles of users in domain can be done only with Server JWT.

Note that there is a standard list of user profile fields predefined. They are:

  • user_name
  • first_name
  • last_name
  • email
  • avatar
  • roles
  • profile All fields above with exception of roles and profile take string values.

roles field accept JSON list of strings to define roles. Values in this list are developer defined and not validated or enforced by Auth Manager.

profile field accepts arbitrary JSON object so the developer can defined and store whatever additional profile information is needed for the application.

curl -X PUT -H "Content-Type: application/json" -H "Bearer <client/server JWT>"
-d '{
    "user_name": "John Smith",
    "first_name": "John",
    "last_name": "Smith",
    "roles": ["team1:owner", "team2:admin"],
    "profile.additional_info": "some data2",
    "profile.additional_obj": {
        "field1": "value1",
        "field2": "value22"
    }
}' https://aum.iris.comcast.net/v1.1/user/profile/userid/{userid}

Result

{
    "message": "success"
}

Get User Profile

Get profile for the specified user.

This API accepts client or server JWT. If client JWT is passed then userID passed in to the API must match the user ID of the client JWT. That is, client JWT cannot retrieve profiles of other users. Retrieving profiles of users in domain can be done only with Server JWT.

curl -X GET -H "Content-Type: application/json" -H "Bearer <client/server JWT>"
https://aum.iris.comcast.net/v1.1/user/profile/userid/{userid}

Sample result:

{
    "avatar": "",
    "email": "test2@test.com",
    "first_name": "John",
    "last_name": "Smith",
    "profile": {
        "additional_info": "some data2",
        "additional_obj": {
            "field1": "value1",
            "field2": "value22"
        }
    },
    "roles": [
        "team1:owner",
        "team2:admin"
    ],
    "user_name": "John Smith"
}

Query User by Profile Fields

Query for users by profile fields.

This API requires Server JWT.

match - valid values are match or contain. If match is used the case sensitive, full word match must occur. If contain is used then the match is successful if the provided value is contained in the field. start - pagination element start count - size of page, that is, number of elements returned

Results return following fields:

user_profiles - list of matched user profiles including user_ids start - start index, it is always equal to passed in start argument count - number of user profiles returned. This can be equal or less than passed in count argument. max - total number of matching user profiles.

curl -X POST -H "Content-Type: application/json" -H "Bearer <client/server JWT>"
-d '{
    "email": "TesT"
}'
https://aum.iris.comcast.net/v1.1/user/query/profile/match/{match}/start/{start}/count/{count}

Sample output when matches found:

200
{
    "user_profiles": [
        {
            "avatar": "",
            "email": "test1@test.com",
            "first_name": "",
            "last_name": "",
            "profile": {},
            "roles": [],
            "user_id": "383320db-7f50-11e7-a7fe-f40f2411368f",
            "user_name": "c3674da0-97ed-11e7-b184-41dc2ee3121f"
        },
        {
            "avatar": "",
            "email": "test2@test.com",
            "first_name": "test2",
            "last_name": "test",
            "profile": {
                "additional_info": "some data2",
                "additional_obj": {
                    "field1": "value1",
                    "field2": "value22"
                }
            },
            "roles": [
                "team1:owner",
                "team2:admin"
            ],
            "user_id": "3bf6a7c0-7f50-11e7-a7fe-f40f2411368f",
            "user_name": "Test2 test"
        },
        {
            "avatar": "",
            "email": "test3@test.com",
            "first_name": "",
            "last_name": "",
            "profile": {},
            "roles": [],
            "user_id": "3e5e665a-7f50-11e7-a7fe-f40f2411368f",
            "user_name": "me me"
        }
    ],
    "start": 0,
    "count": 3,
    "max": 9
}

Sample output when there are no matches:

200
{
    "user_profiles": [],
    "start": 0,
    "count": 0,
    "max": 0
}

Change User Password

This API allows to update user password.

This API accepts client or server JWT. If client JWT is passed then userID passed in to the API must match the user ID of the client JWT. That is, client JWT cannot retrieve profiles of other users.

curl -X PUT -H "Content-Type: application/json" -H "Bearer <client/server JWT>"
-d '{
  "email": "test@test.com",
    "current_password": "password",
    "new_password": "password123"
}'
https://aum.iris.comcast.net/v1.1/password

Success:

200
{
  "message": "Password reset"
}

Failure like current password is not matching:

401
{
  "error": {
    "code": "AUTH_0010",
    "message": "Invalid password"
  }
}

Reset User Password

This API allows application server to reset user password. The main difference between password change and this API is that you do not need to provide current password to change user's password.

This API accepts only server JWT and allows application server to reset password for the user.

curl -X PUT -H "Content-Type: application/json" -H "Bearer <server JWT>"
-d '{
  "email": "test@test.com",
    "new_password": "password123"
}'
https://aum.iris.comcast.net/v1.1/password/reset

Sample output:

200
{
    "message": "Password reset"
}
← Author v1Author Identity API →