NAV Navbar
javascript shell

Introduction

const Ideea = require('ideea-js');

let Ideea = new Ideea('e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855');

This is the documentation for the Ideea platform. This API is used for managing users and groups, creating API Keys and accessing billing information.

To initalize the SDK set the first argument of the class constructer as a valid API Key. You can create a new API key here.

Login

POST /login

ideea.login('[email protected]', 'password').then((accessToken) => {
    console.log(accessToken)
})
curl 'http://api.ideea.io/api/v1/auth/login' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  --data-binary '{"email":"[email protected]","password":"password"}'

Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJrZXkiOiJ2YWwiLCJpYXQiOjE0MjI2MDU0NDV9.eUiabuiKv-8PYk2AkGY4Fb5KMZeorYBLw261JPQD5lM"
}

On the Ideea platfrom requests are authenticated in two ways, with an access token or with an API key. To make a authenticated request, add either your access token or API Key to the headers as shown below.

Authorization: bearer ACCESS_TOKEN

X-Api-Token: API_KEY

To Login (aka generate a new access token) use the .login() method and send your email address and password.

HTTP Request

POST http://api.ideea.io/api/v1/auth/login

Request Payload

Parameter Required Description
email true Your email address
password true Your password

Auth

POST /auth

ideea.auth().then(() => {
    console.log('Success')
}).catch(() => {
    console.log('Fail')
})
curl 'http://api.ideea.io/api/v1/auth' \
  -H "Authorization: bearer ACCESS_TOKEN"

Response

{
  "auth": true
}

If you want to check that your access token or API key is still valid use the auth route. If successful the endpoint will respond with 200 or 401 if not.

HTTP Request

GET http://api.ideea.io/api/v1/auth

User

GET /user

ideea.getUser().then((user) => {
    console.log(user.email);
    console.log(user.first_name);
    console.log(user.last_name);
})
curl 'https://api.ideea.io/api/v1/user' \
  -X GET \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Response

{
  "id": "46438def-9a34-4466-ba4c-46438def7d7f",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "display_name": "John Doe",
  "profile_image": "http://app.ideea.io/api/v1/user/profile-image/john%20doe",
  "type": "admin",
}

To get the current user object hit the /user route. This will return the user asociated with the provided access token or API Key.

HTTP Endpoint

GET http://api.ideea.io/api/v1/user

Query Parameter

Parameter Required Description
with false Use the query param with=groups to return the user model with all groups the user has access to.

Update User

POST /user

ideea.updateUser({
  first_name: 'James',
  last_name: 'Smith'
}).then((user) => {
    console.log(user);
})
curl 'https://api.ideea.io/api/v1/user' \
  -X POST \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json;' \
  --data-binary '{"first_name":"James","last_name":"Smith"}'

Response

{
  "id": "46438def-9a34-4466-ba4c-46438def7d7f",
  "email": "[email protected]",
  "first_name": "James",
  "last_name": "Smith",
  "display_name": "James Smith",
  "profile_image": "http://app.ideea.io/api/v1/user/profile-image/john%20doe",
  "type": "admin",
}

To update the current user make a post request to /user. This will update the user object with the provided data.

HTTP Endpoint

POST http://api.ideea.io/api/v1/user

Query Parameter

Parameter Required Description
first_name false The user's first name
last_name false The user's last name
display_name false The user's display name

Groups

GET /groups/{group_id}

ideea.getGroup('12420628-7d15-4a2b-91fb-af8e27c4943f').then((group) => {
    console.log(group);
})
curl 'https://api.ideea.io/api/v1/groups/12420628-7d15-4a2b-91fb-af8e27c4943f' \
  -X GET \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Response

{
  "id": "12420628-7d15-4a2b-91fb-af8e27c4943f",
  "name": "Ideea",
}

To get a specific group hit /groups/{group_id} this will return the group object. You must have access to the group before you can access this route.

HTTP Endpoint

GET http://api.ideea.io/api/v1/groups/{group_id}

Update Group

POST - /groups/{group_id}

ideea.updateGroup('12420628-7d15-4a2b-91fb-af8e27c4943f', {
  name: 'New Group Name',
}).then((group) => {
    console.log(group);
})
curl 'https://api.ideea.io/api/v1/groups/12420628-7d15-4a2b-91fb-af8e27c4943f' \
  -X POST \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json;' \
  --data-binary '{"name":"New Group Name"}'

Response

{
  "id": "12420628-7d15-4a2b-91fb-af8e27c4943f",
  "name": "Ideea",
}

To update a group make a post request to /groups/{group_id}. This will update the group with the provided data.

HTTP Endpoint

POST http://api.ideea.io/api/v1/groups/{group_id}

Query Parameter

Parameter Required Description
name false Update the group name

Group Users

GET - /groups/{group_id}/users

ideea.getGroupUsers('12420628-7d15-4a2b-91fb-af8e27c4943f').then((users) => {
    users.map(user => {
    console.log(user)
  })
})
curl 'https://api.ideea.io/api/v1/groups/12420628-7d15-4a2b-91fb-af8e27c4943f/users' \
  -X GET \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Response

[
  {
    "id": "46438def-9a34-4466-ba4c-46438def7d7f",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "display_name": "John Doe",
    "profile_image": "http://app.ideea.io/api/v1/user/profile-image/john%20doe",
    "type": "admin",
  },
  ...
]

To get an array of users who have access to a specific group make a GET request to /groups/{group_id}/usres.

HTTP Endpoint

GET http://api.ideea.io/api/v1/groups/{group_id}/users

Add User To Group

POST - /groups/{group_id}/users/add

ideea.addUserToGroup(
  '12420628-7d15-4a2b-91fb-af8e27c4943f',
  '90bc3a782b-7d15-4a2b-91fb-af8e27c4943f',
  'admin'
).then((relationship) => {
    console.log(relationship.user_id);
    console.log(relationship.role);
})
curl 'https://api.ideea.io/api/v1/groups/12420628-7d15-4a2b-91fb-af8e27c4943f/users/add' \
  -X POST \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json;' \
  --data-binary '{"user_id":"90bc3a782b-7d15-4a2b-91fb-af8e27c4943f","role":"admin"}'

Response

{
  "group_id": "12420628-7d15-4a2b-91fb-af8e27c4943f",
  "user_id": "90bc3a782b-7d15-4a2b-91fb-af8e27c4943f",
  "role": "admin",
}

To add a user to a group make a post request to /groups/{group_id}/users/add. You will need to also specify a role which will be either user or admin. If you would like to change the role of a user who is already a member of a group use this endpoint.

HTTP Endpoint

POST http://api.ideea.io/api/v1/groups/{group_id}/users/add

Query Parameter

Parameter Required Description
user_id true The ID of the user you would like to add to the group
role true The role of the user. Use either user or admin.

Remove a User From a Group

POST - /groups/{group_id}/users/remove

ideea.removeUserFromGroup(
  '12420628-7d15-4a2b-91fb-af8e27c4943f',
  '90bc3a782b-7d15-4a2b-91fb-af8e27c4943f',
).then((relationship) => {
    console.log(relationship.user_id);
    console.log(relationship.role);
})
curl 'https://api.ideea.io/api/v1/groups/12420628-7d15-4a2b-91fb-af8e27c4943f/users/remove' \
  -X POST \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json;' \
  --data-binary '{"user_id":"90bc3a782b-7d15-4a2b-91fb-af8e27c4943f"}'

Response

{
  "group_id": "12420628-7d15-4a2b-91fb-af8e27c4943f",
  "user_id": "90bc3a782b-7d15-4a2b-91fb-af8e27c4943f",
}

To remove a user to from a group make a POST request to /groups/{group_id}/users/remove.

HTTP Endpoint

POST http://api.ideea.io/api/v1/groups/{group_id}/users/remove

Query Parameter

Parameter Required Description
user_id true The ID of the user you would like to remove from the group

API Keys

GET /groups/{group_id}/tokens

ideea.getApiKeys('12420628-7d15-4a2b-91fb-af8e27c4943f').then((apiKeys) => {
    apiKeys.map(apiKey => {
    console.log(apiKey)
  })
})
curl 'https://api.ideea.io/api/v1/groups/12420628-7d15-4a2b-91fb-af8e27c4943f/tokens' \
  -X GET \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Response

[
  {
    "id": "a5b4c964-4719-40cd-ab78-354950aaf9e5",
    "group_id": "12420628-7d15-4a2b-91fb-af8e27c4943f",
    "expires_at": null,
    "name": "My First API Key",
    "token": "d090b02a58b002e3f406464dec9e35b4594b9b483fe81781859a78fe0bb1f90",
    "created_at": "2019-02-16T22:58:04.000Z",
    "updated_at": "2019-02-16T22:58:04.000Z"
  },
  ...
]

To get all of the API keys that belong to a group make a GET request to /groups/{group_id}/tokens. This will return an array of API Keys.

HTTP Endpoint

GET http://api.ideea.io/api/v1/groups/{group_id}/tokens

Create an API Key

POST - /groups/{group_id}/tokens/create

ideea.createApiKey('12420628-7d15-4a2b-91fb-af8e27c4943f', {
  name: 'New Api Key',
  expires: '1-week',
  password: 'PASSWORD',
}).then((apiKey) => {
    console.log(apiKey);
})
curl 'https://api.ideea.io/api/v1/groups/12420628-7d15-4a2b-91fb-af8e27c4943f/tokens/create' \
  -X POST \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json;' \
  --data-binary '{"name":"New Api Key","password":"password"}'

Response

{
  "id": "709ee024-bf38-4a08-a4f6-1f20178ef1ba",
  "group_id": "12420628-7d15-4a2b-91fb-af8e27c4943f",
  "expires_at": "2019-03-04T01:22:45.000Z",
  "name": "api-key-8aka6r5nmuj",
  "token": "e3861fec13af26aa53a279f6824e9e0080be76e2770b6c984366f8c5976de509",
  "updated_at": "2019-02-25T01:22:19.520Z",
  "created_at": "2019-02-25T01:22:19.520Z"
}

To create a new API Key make POST request to /groups/{group_id}/tokens/create.

HTTP Endpoint

POST http://api.ideea.io/api/v1/groups/{group_id}/tokens/create

Query Parameter

Parameter Required Description
name true The name of the new API Key
password true The password of the current user
expires false When you would like the key to expire. This can be set to 1-day, 1-week, 1-month or 1-year. If you omit this parameter the key will never expire.

Delete an API Key

DELETE - /groups/{group_id}/tokens/{token_id}/delete

ideea.deleteApiKey(
  '12420628-7d15-4a2b-91fb-af8e27c4943f', 
  '709ee024-bf38-4a08-a4f6-1f20178ef1ba', 
}).then((apiKey) => {
    console.log(apiKey.id);
})
curl 'https://api.ideea.io/api/v1/groups/12420628-7d15-4a2b-91fb-af8e27c4943f/tokens/{token_id}/delete' \
  -X DELETE \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Response

{
  "id": "709ee024-bf38-4a08-a4f6-1f20178ef1ba",
}

To delete an API Key make DELETE request to /groups/{group_id}/tokens/{token_id}/delete.

HTTP Endpoint

POST http://api.ideea.io/api/v1/groups/{group_id}/tokens/{token_id}/delete

Create a One-time-use API Key

POST - /groups/{group_id}/tokens/create/one-time

ideea.createOneTimeUseKey('12420628-7d15-4a2b-91fb-af8e27c4943f').then((apiKey) => {
    console.log(apiKey);
})
curl 'https://api.ideea.io/api/v1/groups/12420628-7d15-4a2b-91fb-af8e27c4943f/tokens/create/one-time' \
  -X POST \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Response

{
  "apikey": "O-73febd1e86ddf0921c58ce92b4b36b0aef787125b7ee5f1fdc6774ae46c1f08f"
}

A one-time-use API Key is a key that will only work for one request. This key can not be used to create more API keys or any kind of admin request. To create a new OTU API Key make POST request to /groups/{group_id}/tokens/create/one-time. This request does not require a payload.

HTTP Endpoint

POST http://api.ideea.io/api/v1/groups/{group_id}/tokens/create/one-time

Errors

The Ideea API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The kitten requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many kittens! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.