The Authum Service API provides the core functionality (client / user registering, user login, user authentication request, etc.) for subscribing third-party applications.

http://authum.hoodbluck.com
https://authum.herokuapp.com

User

User Registration

See [Action Diagram here] (https://cloud.githubusercontent.com/assets/982808/8762580/710a53f4-2d4b-11e5-8077-123ecc2e232b.png).

A user can be registered to Authum service, providing basic information which will be used at a later point to provide it to third party applications while registering new accounts in their infrastructures.

POST /user

Headers

Header	Content
User-Agent	The User-Agent should be com.hoodbluck.ios or com.hoodbluck.android to be a valid registration.

Parameters

Type	Content
application/json	A User. (See Models for 'User' data structure)

Response

If the registration process is successful, it will provide the updated User object with the userId in it. See generic AuthumResponse structure on Models page.

Code	Status	Value	Description
0	success	{user}	The user was successfully registered.
-1	user_invalid	{dynamic validation message}	The user's structure on contents are invalid.
-1	user_already_registered	"This email is already registered"	The user's email is already registered.
-1	user_agent_invalid	"Invalid user agent."	The received user agent header is invalid.

User Device Token Registration

If the deviceToken was not sent in the registration, it can be added later on.

POST /user/{userId}/deviceToken

Parameters

Name	Type	Content
deviceToken	string	The user's device token for notifications.

Response

See generic AuthumResponse structure on Models page.

Code	Status	Value	Description
0	success	"The user device token is updated."	The user's device token is updated.
-1	user_invalid_id	"The user id is invalid."	The userId was invalid.
-1	device_token_invalid	"The device token is invalid."	The deviceToken is invalid.

User Log In

See [Action Diagram here] (https://cloud.githubusercontent.com/assets/982808/8762560/98411666-2d4a-11e5-8f60-f6f66d1cfa7c.png).

A User can log in in the Authum service. The credentials of the user will be required and the registered user will be returned if authorized.

POST /user/login

Parameters

Name	Type	Content
user	string	The user's email.
password	string	The user's password.

Response

If the log in process is successful, it will return the registered User object. See generic AuthumResponse structure on Models page.

Code	Status	Value	Description
0	success	{user}	The credentials are valid.
-1	login_invalid	"The user's email or password is wrong"	The credentials are invalid.

User Authorization Response

If an authorization notification request is presented to the user, it can respond it to the Authum service.

POST /user/{userId}/client/{clientId}/auth/{authorized}

NOTE: This also can be responded via email:

POST /user/email/{userEmail}/client/{clientId}/auth/{authorized}

Path Parameters

Name	Type	Content
authorized	string	"1" if the user accepted, "0" otherwise.

Client

Client Registration

A Client (third-party application) can register to the Authum service.

POST /client

Parameters

Type	Content
application/json	A client. See Models for Client structure.

Response

See generic AuthumResponse structure on Models page.

Code	Status	Value	Description
0	success		The client was registered.

Client Authorization Request

A Client (third-party application) can request authorization to a given user for their application. This is an synchronous call that will wait for the user's authorization with a timeout of 25 seconds.

GET /client/{clientId}/user/{userId}/auth

NOTE: This can also be requested via email:

GET /client/{clientId}/user/email/{userEmail}/auth

Response

See generic AuthumResponse structure on Models page.

Code	Status	Value	Description
0	success	user	The authorized user. See Models for user structure.
-1	user_time_out		The user notification was never engaged.
-1	user_unauthorized		The user declined or failed the notification authentication.

Notification

The notifications are managed through the client's user agent, which currently supports GCM (Google's Cloud Message) and APNS (Apple Push Notification Service).

APNS Notification

The APNS Notification's payload:

{
    "aps": {
        "alert": "Alert content",
        "category": "AUTHENTICATE_CATEGORY",
        "sound": "default"
    },
    "clientId": "clientId"
}

NOTE: The clientId is a String

GCM Notification

The GCM Notification's payload:

{
    "registration_ids": "registrationId",
    "data": {
        "contentType": "payload",
        "data": {
            "message": "Alert message",
            "clientId": "clientId"
        }
    }
}

NOTE: The clientId is a String