-
Notifications
You must be signed in to change notification settings - Fork 0
Schema Auth
Authorization is only required for write access and accessing sensitive data. Most of the API is wide open for GET access.
Authorization is managed using token model authentication. First you need to log in to retreive the auth tokens. then pass the tokens with each http request.
Currently I can create "application" role reqeusts where the application is responsible for providing parameters about which commander is making an update.
Alternatively it is possible to create individual commander profiles and make changes on a per commander basis. This approach is more ideal for web applications because the user themselves can register and use their own credentials. I still need to fully test and document the registration process though.
Example:
curl -i -H "Accept: application/vnd.json+api" -H "Content-Type: application/vnd.json+api" -X POST -d '{"email": "[email protected]", "password": "SECRET"}' http://api.edmaterializer.com/auth/sign_in
This will give you the necessary tokens in the header response.
The values you will need to send with requests are:
- uid (your account email)
- access_token
- client
This is for Indivial commander accounts only.
The HTTP routes match the ones documented here: https://github.com/lynndylanhurley/devise_token_auth
... except! Mine are prefixed by /auth/ route. So the full (relevent) list is:
| path | method | purpose |
|---|---|---|
| /auth/ | POST | Email registration. Requires email, password, and password_confirmation params. A verification email will be sent to the email address provided. Accepted params can be customized using the devise_parameter_sanitizer system. |
| /auth/ | DELETE | Account deletion. This route will destroy users identified by their uid and auth_token headers. |
| /auth/ | PUT | Account updates. This route will update an existing user's account settings. The default accepted params are password and password_confirmation, but this can be customized using the devise_parameter_sanitizer system. If config.check_current_password_before_update is set to :attributes the current_password param is checked before any update, if it is set to :password the current_password param is checked only if the request updates user password. |
| /auth/sign_in | POST | Email authentication. Requires email and password as params. This route will return a JSON representation of the User model on successful login along with the access-token and client in the header of the response. |
| /auth/sign_out | DELETE | Use this route to end the user's current session. This route will invalidate the user's authentication token. You must pass in uid, client, and access-token in the request headers. |
| /auth/validate_token | GET | Use this route to validate tokens on return visits to the client. Requires uid, client, and access-token as params. These values should correspond to the columns in your User table of the same names. |
| /auth/password | POST | Use this route to send a password reset confirmation email to users that registered by email. Accepts email and redirect_url as params. The user matching the email param will be sent instructions on how to reset their password. redirect_url is the url to which the user will be redirected after visiting the link contained in the email. |
| /auth/password | PUT | Use this route to change users' passwords. Requires password and password_confirmation as params. This route is only valid for users that registered by email (OAuth2 users will receive an error). It also checks current_password if config.check_current_password_before_update is not set false (disabled by default). |
| /auth/password/edit | GET | Verify user by password reset token. This route is the destination URL for password reset confirmation. This route must contain reset_password_token and redirect_url params. These values will be set automatically by the confirmation email that is generated by the password reset request. |
After logging in and retrieving the tokens you can test your validation tokens with this GET url (subtituating the 3 params with your tokens):
Here is a sample POST request with auth headers are being passed along using the unix command curl.
curl -i -H "Accept: application/vnd.json+api" -H "Content-Type: application/vnd.json+api" -H "access-token: ACCESS_TOKEN_HERE" -H "client: CLIENT_NAME_HERE" -H "uid: ACCOUNT_EMAIL_HERE" -X POST -d '{"data": {"attributes": {"system-name": "TestSystem", "updater": "Marlon Blake", "world": "Marlingrad"}, "type"=>"worlds"}}' http://api.edmaterializer.com/api/v3/worlds