Skip to content

Account API

Account

Add a contact

POST /account/contact/

Name Type Description
contactId [String] ID of the contact to add.
contactEmail [String] Email of the contact to add.
Example usage: 
curl -X POST -H 'Authorization: Bearer <auth_token>' -d '{"contactId": "e000be0092e6089543988bb2"}' 'https://smartshape.io/account/contact/'
Success-Response: 
HTTP/1.1 200 OK
{
    "success": true,
    "id": "6089543988bb2e000be0092e"
}
Error-Response: 
HTTP/1.1 409 Conflict
{
    status: 409,
    title: 'Conflict',
    detail: 'This contact already exists in the owner contact list.',
    code: 'CONTACT_ALREADY_EXISTS'
 }
Error-Response: 
HTTP/1.1 400 Bad Request
{
    status: 400,
    title: 'Bad Request',
    detail: 'A contact must have at most a contactId or a contactEmail, not both.',
    code: 'TOO_MANY_ARGUMENTS'
 }

Add a role

POST /account/role/

Name Type Description
name String Name of the role.
permissions String Permissions of the role.
Example usage: 
curl -X POST \
  https://smartshape.io/account/role/ \
  -H 'Authorization: Bearer <auth_token>' \
  -d '{
     "name": "Manager",
     "permissions": ["edit_scene_node_attribute"]
  }'
Success-Response: 
HTTP/1.1 200 OK
{
    "success": true,
    "id": "6089543988bb2e000be0092e"
}
Error-Response: 
HTTP/1.1 409 Conflict
{
    "status": 409,
    "title": "Conflict",
    "detail":"A role with this name already exists."
}

Create a new Session

Example usage: 
curl -X POST 'https://smartshape.io/account/session' \
    -H 'Authorization: Bearer <auth_token>'
Success-Response: 
HTTP/1.1 200 OK
{
    "success": true,
    "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6I..."
}

Success 200

Name Type Description
A Object JSON object containing the Session JWT.
Error-Response: 
HTTP/1.1 402 Payment Required
{
    "error": {
        "status": 402,
        "detail": "No free Token available",
        "title": "Payment Required"
    }
}
Error-Response: 
HTTP/1.1 409 Unauthorized
{
    "error": {
        "status": 409,
        "detail": "A Session already exists for this Account",
        "title": "Conflict"
    }
}
Error-Response: 
HTTP/1.1 401 Unauthorized
{
    "code": 401,
    "detail": "Invalid JWT",
    "title": "Unauthorized"
}

Create a new account

POST /account/

Name Type Description
email String Email of the account.
password String optional Password of the account in plain text. Required by default and when strategy.name == "local". Must not be specified otherwise.
username String optional Username of the account. Deduced from the email address if not provided.
permissions [String] optional Permissions of the account. Can be any arbitrary array of strings.
roles [String] optional Roles of the account. Can be any array of Role IDs.
strategy.name [String] optional Name of the strategy used to create the Account.
Possible values:
- LDAP: The Account comes from an LDAP directory.
- local: The Account is local to SmartShape.
Example usage: 
curl -X POST https://smartshape.io/account/ -H 'Authorization: Bearer <auth_token>' -d '{"email": "test4@smartshape.io", "password": "test"}'
Success-Response: 
HTTP/1.1 200 OK
{
    "success": true,
    "id": "6089543988bb2e000be0092e"
}
Error-Response: 
HTTP/1.1 400 Bad Request
{
    "status": 409,
    "detail": "A user with this email address already exists.",
    "title": "Conflict"
}

Delete a contact

URL /account/contact/:contactId

Name Type Description
contactId String ID of the contact to delete.
Example usage: 
curl -X DELETE -H 'Authorization: Bearer <auth_token>' 'https://smartshape.io/account/contact/000be0092e6089543988bb2e'
Success-Response: 
HTTP/1.1 200 OK
{
    "success": true,
    "id": "6089543988bb2e000be0092e"
}

Delete a role

URL /account/role/:roleId

Name Type Description
roleId String ID of the role to delete.
Example usage: 
curl -X DELETE \
  https://smartshape.io/account/role/delete/5b3497c46fcfde308ad3b7df \
  -H 'Authorization: Bearer <auth_token>'
Success-Response: 
HTTP/1.1 200 OK
{
    "success": true,
    "id": "6089543988bb2e000be0092e"
}

Delete an account

URL /account/:accountId

Name Type Description
accountId String ID of the account to be deleted.
Example usage: 
curl -X DELETE \
  https://smartshape.io/account/6089543988bb2e000be0092e \
  -H 'Authorization: Bearer <auth_token>'
Success-Response: 
HTTP/1.1 200 OK
{
    "success": true,
    "id": "6089543988bb2e000be0092e"
}

Delete the current Session

Example usage: 
curl -X DELETE \
  https://smartshape.io/account/session \
  -H 'Authorization: Bearer <auth_token>' \
  -H 'X-SmartShape-Session: <jwt>'
Success-Response: 
HTTP/1.1 200 OK
{
    "success": true
}
Error-Response: 
HTTP/1.1 401 Unauthorized
{
    "code": 401,
    "detail": "Invalid JWT",
    "title": "Unauthorized"
}
Error-Response: 
HTTP/1.1 401 Unauthorized
{
    "code": 401,
    "detail": "Invalid session JWT",
    "title": "Unauthorized"
}
Error-Response: 
HTTP/1.1 401 Unauthorized
{
    "code": 401,
    "detail": "No session found for the current user",
    "title": "Unauthorized"
}

Get a user avatar

accountId /account/avatar/:accountId?

Name Type Description
accountId String ID of the requested account avatar (optional).
Example usage: 
curl -X GET \
  https://smartshape.io/account/avatar/5b3497c46fcfde308ad3b7df \
  -H 'Authorization: Bearer <auth_token>'
Success-Response: 
HTTP/1.1 302 OK
Found. Redirecting to https://secure.gravatar.com/avatar/c4fa5d106b35b657593acce1c9edfde9?r=g&d=mm&s=200

List all SmartShape accounts

Success-Reponse: 
HTTP/1.1 200 OK
{
   "success": true,
   "accounts": [
     {
        "id": "5fca693d1256352948b5fa9d",
        "username": "test",
        "email": "test@smartshape.io",
        "roles": [],
        "permissions": [],
        "strategy": {
            "name": "local"
        }
     }
   ]
}

List all contacts

Example usage: 
curl -X GET -H 'Authorization: Bearer <auth_token>' 'https://smartshape.io/account/contact/'
Success-Response: 
HTTP/1.1 200 OK
{
    "success": true,
    "contacts": [{
        "id": "901d404fb446623684892c0d",
        "owner": "5fca693d1256352948b5fa9d",
        "contact": {
            "id": "52948b5fa9d5fca693d12563",
            "username": "test2"
        },
        "date": 1484575956625
    }]
}

List all roles

Example usage: 
curl -X GET \
   https://smartshape.io/account/role/ \
   -H 'Authorization: Bearer <auth_token>'
Success-Response: 
HTTP/1.1 200 OK
{
    "success": true,
    "roles": [{
         "id": "5b33af50b6943e69cda5591f",
         "name": "Manager",
         "permissions": [
             "edit_scene_node_attribute"
         ]
     }]
 }

List all the permissions of the current SmartShape Account (including the ones specific to the current File)

Success-Reponse: 
HTTP/1.1 200 OK
{
   "success": true,
   "permissions": [
       "permission_1",
       "permission_2"
   ]
}

Log account out

Example usage: 
curl -X GET 'https://smartshape.io/account/logout'
Success-Response: 
HTTP/1.1 200 OK
{
    "success": true
}

Login account

POST /account/login/

Name Type Description
username String Account username (cannot be used with email).
email String Account email (cannot be used with username).
password String Account password.
Example usage: 
curl -X POST 'https://smartshape.io/account/login/' \
   --data '{
      "username":"test",
      "password":"test"
   }'
Success-Response: 
HTTP/1.1 200 OK
{
    "success": true,
    "username": "test",
    "email": "test@smartshape.io",
    "roles": ["6105f15bd5b76604f33330e7"],
    "permissions": [
        "create_account",
        "delete_account"
    ],
    "strategy": {
        "name": "local"
    },
    "id": "60894bafbd56ffadb446065a",
    "cookies": "jsonwebtoken=eyJhbGciOiJSUzI1NiIsInR5cCI6I..."
}

Success 200

Name Type Description
success Boolean
email String Email of the account.
username String Username of the account.
cookies String Cookies that contain the JWT.
strategy.name String Name of the strategy used to create the Account.
Possible values:
- LDAP: The Account comes from an LDAP directory.
- local: The Account is local to SmartShape.
Error-Response: 
HTTP/1.1 401 Unauthorized
{
    "code": 401,
    "detail": "Invalid credentials.",
    "title": "Unauthorized"
}

Retrieve the details of an account

Example usage: 
curl -X GET -H 'Authorization: Bearer <auth_token>' 'https://smartshape.io/account/6089543988bb2e000be0092e'
Success-Response: 
HTTP/1.1 200 OK
{
    "username": "test",
    "email": "test@smartshape.io",
    "roles": ["6105f15bd5b76604f33330e7"],
    "permissions": [
        "create_account",
        "delete_account"
    ],
    "strategy": {
        "name": "local"
    },
    "id": "604f33330e76105f15bd5b76"
}

Success 200

Name Type Description
id String ID of the account.
username String Username of the account.
email String Email of the account.
String optional permissions Permissions specific to the account.
strategy.name String Name of the strategy used to create the Account.
Possible values:
- LDAP: The Account comes from an LDAP directory.
- local: The Account is local to SmartShape.

Update a Session to keep it alive

Example usage: 
curl -X PATCH \
  https://smartshape.io/account/session \
  -H 'Authorization: Bearer <auth_token>' \
  -H 'X-SmartShape-Session: <jwt>'
Success-Response: 
HTTP/1.1 200 OK
{
    "success": true
}
Error-Response: 
HTTP/1.1 401 Unauthorized
{
    "code": 401,
    "detail": "Invalid JWT",
    "title": "Unauthorized"
}
Error-Response: 
HTTP/1.1 401 Unauthorized
{
    "code": 401,
    "detail": "Invalid session JWT",
    "title": "Unauthorized"
}
Error-Response: 
HTTP/1.1 401 Unauthorized
{
    "code": 401,
    "detail": "No session found for the current user",
    "title": "Unauthorized"
}

Update a role

URL /account/role/:roleId

Name Type Description
roleId String ID of the role to update.

POST /account/role/:roleId

Name Type Description
name String Name of the role.
permissions String Permissions of the role.
Example usage: 
curl -X POST \
 'https://smartshape.io/account/role/update/5b3497c46fcfde308ad3b7df' \
 -H 'Authorization: Bearer <auth_token>' \
 -d '{
    "name": "Manager",
    "permissions": ["edit_scene_node_attribute"]
 }'
Success-Response: 
HTTP/1.1 200 OK
   {
       "success": true,
       "id": "6089543988bb2e000be0092e"
   }

Update an account

URL /account/:accountId

Name Type Description
accountId String ID of the account to be updated.
Example usage: 
curl -X PUT \
  https://smartshape.io/account/5fca693d1256352948b5fa9d \
  -H 'Authorization: Bearer <auth_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "email": "test6@smartshape.io"
  }'
Success-Response: 
HTTP/1.1 200 OK
{
    "success": true,
    "id": "6089543988bb2e000be0092e"
}
April 27, 2023 April 27, 2023