Access From Native Apps

Access from Native Apps

Secure access from native apps is achieved by requiring an 'app access token' along with each request, in the 'X-App-Access-Token' header. Remember to carry out all communication over HTTPS for security!

See the Advanced Setup section for how to create a valid app access token.

Errors from any endpoint can be in one of the following two formats:

{ "error": "some error" }

OR

{ "errors": { "some-key": "some error", ... } }

User Registration

New users can be registered via the following endpoint:

/api/users/sign_up

The following information needs to be sent:

{
  user: {
    "email": "some@email.com",
    "password": "somepassword"
  }
}

If the user is registered successfully, the user's details are returned, as follows:

{
  user: {
    "id": 434899 (for example),
    "email": "some@email.com",
    "confirmed": false (or true),
    "authentication_token": "sometoken" (if authenticated after creation)
  }
}

To delete a user, send a DELETE request to the following endpoint:

/api/users

Deletion only succeeds in one case: a signed in user deleting itself.

See the following files for more:

• /app/controllers/api/users/registrations_controller.rb
• /app/views/api/users/registrations/create.json.jbuilder

Authentication via Password

To authenticate a user with an email and password, send a request identical to the regitsration request, to the following endpoint:

/api/users/sign_in

If the user is authenticated successfully, the user's details are returned as follows:

{
  user: {
    "id": 434899,
    "email: "some@email.com,
    "authentication_token": "sometoken"
  }
}

Authentication via Facebook (or Other Providers)

To authenticate a user via Facebook or another provider, send a request to the same endpoint, as follows:

{
  user: {
    "provider": "facebook" (or other),
    "uid": 12309939 (i.e. the provider's ID for the user),
    "email": "some@email.com"
  }
}

If a user corresponding to the provider and UID exists, it is signed in. Otherwise, a new user is created using the email address provided, and if the user creation is successful, is signed in. The response is as above.

For more on both password and provider based authentication, see:

• /app/controllers/api/users/sessions_controller.rb
• /app/views/api/users/sessions/create.json.jbuilder

Authenticated Requests

To make an authenticated request to any endpoint, include the user's email and authentication token (see above) in the following request headers:

• X-User-Email
• X-User-Authentication-Token