# Authentication
The ControlByWeb.Cloud api uses OAuth 2.0 for authentication. A bearer token passed through an HTTP Authorization header is required for most api endpoints.
# get token (login)
A bearer token can be retrieved from this endpoint using a username, password and grant_type of "password". It will be associated with the user whose credentials are used to request the token. The permissions of the user will determine what other endpoints are accessible in the api. The api will limit access to the account the user belongs to as well as any child accounts.
Bearer tokens have a finite lifetime of 24 hours. Once a bearer token expires, this endpoint can be reused to renew the token using the refresh_token and a grant_type of "refresh_token". Upon first authentication this endpoint will return the user information and permissions as well as account information.
The returned permissions field holds a list of permission strings for the user. The all_permissions field holds a list of all permissions possible in the api. Checks can be made for permissions strings to determine if an option should be made available in the webpage or application. For example, if a permission of "Add Users" exists for the user then it is alright to show a button for adding users in the application. The endpoint for adding new users will work for this logged in user. If, on the other hand, the "Add Users" permission is missing, then the add user button should be hidden. Calls to the add user endpoint will not function for this logged in user.
# POST /v1/auth/token
# Parameters
| Name | Type | Description |
|---|---|---|
| grant_type | string | grant_type="password" for initial login in, grant_type="refresh_token" to refresh token |
| username | string | username for the user requesting authentication when grant_type="password" |
| password | string | password for the user requesting authentication when grant_type="password" |
| refresh_token | string | refresh_token when grant_type="refresh_token" |
# Example
curl -X POST "https://api.controlbyweb.cloud/api/v1/auth/token" \
-d "grant_type={grant_type}" \
-d "username={username}" \
-d "password={password}"
# Response
{
"token_type": "Bearer",
"expires_in": 86400,
"access_token": "IpJHTfDUJfifqjPYscNa8CciMQsMuY0m-A9ZOV2hVdDEO-vKL46k76HUxJe-7fHCbNRrwuWquqSSqY7Ybeijebj86daOFLeWahWB_otcIF3pzm1uXgeoP0nzk1zd2FWU-yaEBN9sDB4t5e7SZu6Zs2D_bH6iKrAX8D1aHwPFSjfE6_md-nAuWPFaXAwjAgGrxo_9K4H0mEt4HDhrbcpeyJ0eXAiOiJKVKlg9_NvTLJecMzcJ_QCuWljqKPs4L_3hbsqclKEEQn6AyZDA5NzNiYWFkZjJlOTMiLCJpYXQiOjE2MDMxMjUwOTYsIm5iZiI6MTYwMzEyNTA5NiwiZXhwIjoxNjAzMjExNDk2LCJzdgpftLjbTqUa5G3rsf7nzwJPQJTusVxjdcpPq-mcfBw4-_2VT2am4qyTLhKeVVjjmnZay2KuEZDLtjU1uCUeRSTEZf57PEiD1n7BBHEIRWIiOiIxIiwic2NvcGVzIjpbXX0Kn5wldGJt-atbw2JOSvuHXwWb4ABYTxfcZttNYcTAzw.8bdSJqpzGGu3Arzn5wtdGrTY1m6oK1JXyefh0T24rfu0AwYWM1MTEwZTRlMTAxZDRkY2E1NWQzY2I5NjY4M2IyMWFhMzlhY2ViODk1ZjEzM2JlZTZlZjF5kzOcYNGL8bkTdnmav4dXWCMThNTwSy3IpnkcO1veywGgOG62McFn4Qk8FpfRc6xvmjmKsa6txhFYsLRwKkR_sUF-3iN4ERcrmiqmqCwR12OLlg_O83kB5OHbeFVycF2laNmip1lTqZq1xXvxj0dBzfI5CLG_wUO0ctfzf1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIyIiwianRpIjoiNzFmMDk5wOZnOeM6lwTGZL36vfgYyFhoytQOGX5_yt4qL3YGW28gVp_qGzbi8w4jhoB8S4XZ5dkzaHSa_MI",
"refresh_token": "def50200195542c75c98500467241c628799b25c0c025bf64e0a0757c9386aebf063a01b2cb4949d966d8135c350581b4982fe46578c8629ec745d6b656754f04b26a2547a448e5105e94b2c24e1686faaace18d60eac362815cd600a450d9b377403704d85241164b1a1e507725d924700f2929086e7f369832fffc54dcc873331de1ccc790bb41973928de5dbc2b32c8822091b57c9e7926348c315d7c9e092e272ea5de4b9d4794c1ae697ee6f00fc0448479e525ed0841bfee3627285990065ab6031369cc9d4f1f3d8374b7929024bbcd3f763abd4a9ce795de23ee58723b1efacaed3395732076f8a2ff73f26b1bcecb43a7221080312aaba976427ac3cc3c9f18d33e3614138f2dcdd8c65369350a3b1c587afd1f87e2bacb5295003db9cfac202c0346d490692397a0ae25703155fd3135fd6e35325c8b018bd9a9ef685303afed3ed03a3849aff14399c55d1cf2c6217eacff72d8c7965cd1a30ccf23",
"account_id": 1234,
"username": "foobarbaz",
"first_name": "Foo",
"last_name": "Bar",
"email": "foobar@controlbyweb.com",
"device_seats": 5000,
"account_name": "Xytronix Research & Design",
"logging": 2,
"user_id": 1,
"agreed": 1,
"permissions": [
"Setup Devices"
"Control Devices"
"View Logged Data"
"Add Devices"
"Edit Devices"
"Delete Devices"
"Add Device Tags"
"Edit Device Tags"
"Delete Device Tags"
"Add DAT Urls"
"Edit DAT Urls"
"Delete DAT Urls"
"Add Users"
"Edit Users"
"Delete Users"
"Add Accounts"
"Edit Accounts"
"Delete Accounts"
"Add Remote Log Servers"
"Edit Remote Log Servers"
"Delete Remote Log Servers"
"Edit Permissions"
],
"all_permissions": [
{
"id": "Admin",
"label": "Admin",
"children": [
{
"id": "Device Operator",
"label": "Device Operator",
"children": [
{
"id": "Setup Devices",
"label": "Setup Devices"
},
{
"id": "Control Devices",
"label": "Control Devices"
},
{
"id": "View Logged Data",
"label": "View Logged Data"
}
]
},
{
"id": "Device Manager",
"label": "Device Manager",
"children": [
{
"id": "Add Devices",
"label": "Add Devices"
},
{
"id": "Edit Devices",
"label": "Edit Devices"
},
{
"id": "Delete Devices",
"label": "Delete Devices"
}
]
},
{
"id": "Device Tag Manager",
"label": "Device Tag Manager",
"children": [
{
"id": "Add Device Tags",
"label": "Add Device Tags"
},
{
"id": "Edit Device Tags",
"label": "Edit Device Tags"
},
{
"id": "Delete Device Tags",
"label": "Delete Device Tags"
}
]
},
{
"id": "DAT Urls Manager",
"label": "DAT Urls Manager",
"children": [
{
"id": "Add DAT Urls",
"label": "Add DAT Urls"
},
{
"id": "Edit DAT Urls",
"label": "Edit DAT Urls"
},
{
"id": "Delete DAT Urls",
"label": "Delete DAT Urls"
}
]
},
{
"id": "User Manager",
"label": "User Manager",
"children": [
{
"id": "Add Users",
"label": "Add Users"
},
{
"id": "Edit Users",
"label": "Edit Users"
},
{
"id": "Delete Users",
"label": "Delete Users"
}
]
},
{
"id": "Account Manager",
"label": "Account Manager",
"children": [
{
"id": "Add Accounts",
"label": "Add Accounts"
},
{
"id": "Edit Accounts",
"label": "Edit Accounts"
},
{
"id": "Delete Accounts",
"label": "Delete Accounts"
}
]
},
{
"id": "Remote Log Servers Manager",
"label": "Remote Log Servers Manager",
"children": [
{
"id": "Add Remote Log Servers",
"label": "Add Remote Log Servers"
},
{
"id": "Edit Remote Log Servers",
"label": "Edit Remote Log Servers"
},
{
"id": "Delete Remote Log Servers",
"label": "Delete Remote Log Servers"
}
]
}
]
}
],
"isXRDIAdmin": 0,
"isXRDISales": 0,
}
# logout
Invalidate a bearer token and it's associated refresh token. Future calls to the api endpoints using the bearer token will not work anymore. Use this endpoint for logging users out of custom applications / websites.
# POST /v1/auth/logout
# Parameters
| Name | Type | Description |
|---|---|---|
| authToken | string | Bearer Token previous call to get token |
# Example
curl -X POST "https://api.controlbyweb.cloud/api/v1/auth/logout" \
-H "Authorization: Bearer {authToken}"
# Response
{
"message": "success"
}
# reset password link
# POST /v1/auth/reset-password
This endpoint will check if the email address exists in the database and send a password reset email to the address. This endpoint can be used on a 'Forgot Password' page to send the user an email with instructions on how to reset their password.
# Parameters
| Name | Type | Description |
|---|---|---|
| string | the email of the user that needs their password reset |
# Example
curl -X POST "https://api.controlbyweb.cloud/api/v1/auth/reset-password" \
-d "email={email}"
# Response
{
"message": "Password reset email sent.",
"data": "passwords.sent"
}
# reset password
# POST /v1/auth/reset/password
Uses the token recieved from the call to reset password link to validate the password reset request and set the new password to the password provided. This endpoint can be used on a reset password page where the user must enter their new password and submit the page to change their password. The reset password page will be navigated to from an link in a reset password email, and will recieve a token that authorizes the password change.
# Parameters
| Name | Type | Description |
|---|---|---|
| string | the email of the user that needs thier password reset | |
| password | string | the user's new password |
| password_confirmation | string | the user's new password again for verification |
| token | string | token provided from email sent by call to reset password link |
# Example
curl -X POST "https://api.controlbyweb.cloud/api/v1/auth/reset-password" \
-d "email={email}" \
-d "password={password}" \
-d "password_confirmation={password_confirmation}" \
-d "token={token}"
# Response
{
"message": "Password reset successfully."
}
#
← Introduction Accounts →