Clients

Note

This help should be accurate and comprehensive. If you see anything missing or that needs to be fixed, see How to Contribute or let us know in the Juice Slack #documentation channel.

The Clients endpoints provide a way to view clients and their sites, users, apps and invitations.

Listing Clients

GET /api/v1/jb/clients/

Get a list of clients

Example Request:

GET /api/v1/jb/clients/
Accept: application/json
Authorization: Token 7297b3ebb0e7f7baf5f54d39908dda99f5ea8665

Example Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

[
  {
    "id": 1,
    "site": {
      "domain": "localhost:8000",
      "formatted_name": "localhost"
    },
    "name": "Juicebox",
    "default_from_email": "",
    "invitation_subject": "",
    "invitation_body": "",
    "login_title": "Welcome to Juicebox",
    "login_subtitle": "",
    "support_email": "support@juiceanalytics.com",
    "home_location": "/",
    "subtitle_404": "Oops, the application you're looking for does not exist.",
    "message_404": "You may want to head back to the homepage.<br />If you think something is broken, report a problem.",
    "subtitle_500": "Looks like we're having some server issues.",
    "message_500": "Go back to the previous page and try again. If you think something is broken, report a problem.",
    "password_min_length": 8,
    "password_allow_common": false,
    "password_require_numeric": false,
    "password_require_upper": false,
    "password_require_lower": false,
    "password_require_special": false,
    "password_expiration_days": 0
  }
]
Response JSON Array of Objects:
 
  • id (int) – the id of the client
  • site (object) – the site details for the client
  • name (string) – the client name
  • default_from_email (string) – the email address used in emails sent from the system
  • invitation_subject (string) – the subject used in invite emails (If not supplied, defaults to: “You’ve been invited to”)
  • invitation_body (string) – additional test to include in the invite email
  • login_title (string) – the title shown on the login screen
  • login_subtitle (string) – the subtitle shown on the login screen
  • support_email (string) – the email address they should contact for support
  • home_location (string) – the URL that users should be directed to by default
  • subtitle_404 (string) – the subtitle shown when the user access a page that cannot be found
  • message_404 (string) – the message shown when the user access a page that cannot be found
  • subtitle_500 (string) – the subtitle shown when the user encounters an error
  • message_500 (string) – the message shown when the user encouters an error
  • password_min_length (int) – Passwords must be at least this many characters long
  • password_allow_common (boolean) – Allow commonly used passwords
  • password_require_numeric (boolean) – Require users to have a number in their password
  • password_require_upper (boolean) – Require users to have an uppercase letter in their password
  • password_require_lower (boolean) – Require users to have an lowercase letter in their password
  • password_require_special (boolean) – Require users to have an special character (like ‘!@#$%’) in their password
  • password_expiration_days (int) – Require users to change their password after this number of days, 0=disabled
Request Headers:
 
  • Accept – the response content type depends on Accept header
  • Authorization – contains the token to be used for authentication
Response Headers:
 
Status Codes:

Get Client Details

GET /api/v1/jb/clients/(int: id)/

Get details for a client

Example Request:

GET /api/v1/jb/clients/1/
Accept: application/json
Authorization: Token 7297b3ebb0e7f7baf5f54d39908dda99f5ea8665

Example Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript


{
  "id": 1,
  "site": {
    "domain": "localhost:8000",
    "formatted_name": "localhost"
  },
  "name": "Juicebox",
  "default_from_email": "",
  "invitation_subject": "",
  "invitation_body": "",
  "login_title": "Welcome to Juicebox",
  "login_subtitle": "",
  "support_email": "support@juiceanalytics.com",
  "home_location": "/",
  "subtitle_404": "Oops, the application you're looking for does not exist.",
  "message_404": "You may want to head back to the homepage.<br />If you think something is broken, report a problem.",
  "subtitle_500": "Looks like we're having some server issues.",
  "message_500": "Go back to the previous page and try again. If you think something is broken, report a problem.",
  "password_min_length": 8,
  "password_allow_common": false,
  "password_require_numeric": false,
  "password_require_upper": false,
  "password_require_lower": false,
  "password_require_special": false,
  "password_expiration_days": 0
}
Parameters:
  • id (int) – the id of the client
Response JSON Object:
 
  • id (int) – the id of the client
  • site (object) – the site details for the client
  • name (string) – the client name
  • default_from_email (string) – the email address used in emails sent from the system
  • invitation_subject (string) – the subject used in invite emails (If not supplied, defaults to: “You’ve been invited to”)
  • invitation_body (string) – additional test to include in the invite email
  • login_title (string) – the title shown on the login screen
  • login_subtitle (string) – the subtitle shown on the login screen
  • support_email (string) – the email address they should contact for support
  • home_location (string) – the URL that users should be directed to by default
  • subtitle_404 (string) – the subtitle shown when the user access a page that cannot be found
  • message_404 (string) – the message shown when the user access a page that cannot be found
  • subtitle_500 (string) – the subtitle shown when the user encounters an error
  • message_500 (string) – the message shown when the user encouters an error
  • password_min_length (int) – Passwords must be at least this many characters long
  • password_allow_common (boolean) – Allow commonly used passwords
  • password_require_numeric (boolean) – Require users to have a number in their password
  • password_require_upper (boolean) – Require users to have an uppercase letter in their password
  • password_require_lower (boolean) – Require users to have an lowercase letter in their password
  • password_require_special (boolean) – Require users to have an special character (like ‘!@#$%’) in their password
  • password_expiration_days (int) – Require users to change their password after this number of days, 0=disabled
Request Headers:
 
  • Accept – the response content type depends on Accept header
  • Authorization – contains the token to be used for authentication
Response Headers:
 
Status Codes:

Update Client Details

PATCH /api/v1/jb/clients/(int: id)/

Update details for a client

Example Request:

PATCH /api/v1/jb/clients/1/
Accept: application/json
Authorization: Token 7297b3ebb0e7f7baf5f54d39908dda99f5ea8665

{
  "name": "My Client Name"
}

Example Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "id": 1,
  "site": {
    "domain": "localhost:8000",
    "formatted_name": "localhost"
  },
  "name": "My Client Name",
  "default_from_email": "",
  "invitation_subject": "",
  "invitation_body": "",
  "login_title": "Welcome to Juicebox",
  "login_subtitle": "",
  "support_email": "support@juiceanalytics.com",
  "home_location": "/",
  "subtitle_404": "Oops, the application you're looking for does not exist.",
  "message_404": "You may want to head back to the homepage.<br />If you think something is broken, report a problem.",
  "subtitle_500": "Looks like we're having some server issues.",
  "message_500": "Go back to the previous page and try again. If you think something is broken, report a problem."
  "password_min_length": 8,
  "password_allow_common": false,
  "password_require_numeric": false,
  "password_require_upper": false,
  "password_require_lower": false,
  "password_require_special": false,
  "password_expiration_days": 0
}
Parameters:
  • id (int) – the id of the client
Request JSON Object:
 
  • name (string) – the client name (optional)
  • default_from_email (string) – the email address used in emails sent from the system (optional)
  • invitation_subject (string) – the subject used in invite emails (If not supplied, defaults to: “You’ve been invited to”) (optional)
  • invitation_body (string) – additional test to include in the invite email (optional)
  • login_title (string) – the title shown on the login screen (optional)
  • login_subtitle (string) – the subtitle shown on the login screen (optional)
  • support_email (string) – the email address they should contact for support (optional)
  • home_location (string) – the URL that users should be directed to by default (optional)
  • subtitle_404 (string) – the subtitle shown when the user access a page that cannot be found (optional)
  • message_404 (string) – the message shown when the user access a page that cannot be found (optional)
  • subtitle_500 (string) – the subtitle shown when the user encounters an error (optional)
  • message_500 (string) – the message shown when the user encouters an error (optional)
  • password_min_length (int) – Passwords must be at least this many characters long
  • password_allow_common (boolean) – Allow commonly used passwords
  • password_require_numeric (boolean) – Require users to have a number in their password
  • password_require_upper (boolean) – Require users to have an uppercase letter in their password
  • password_require_lower (boolean) – Require users to have an lowercase letter in their password
  • password_require_special (boolean) – Require users to have an special character (like ‘!@#$%’) in their password
  • password_expiration_days (int) – Require users to change their password after this number of days, 0=disabled
Response JSON Object:
 
  • id (int) – the id of the client
  • site (object) – the site details for the client
  • name (string) – the client name
  • default_from_email (string) – the email address used in emails sent from the system
  • invitation_subject (string) – the subject used in invite emails (If not supplied, defaults to: “You’ve been invited to”)
  • invitation_body (string) – additional test to include in the invite email
  • login_title (string) – the title shown on the login screen
  • login_subtitle (string) – the subtitle shown on the login screen
  • support_email (string) – the email address they should contact for support
  • home_location (string) – the URL that users should be directed to by default
  • subtitle_404 (string) – the subtitle shown when the user access a page that cannot be found
  • message_404 (string) – the message shown when the user access a page that cannot be found
  • subtitle_500 (string) – the subtitle shown when the user encounters an error
  • message_500 (string) – the message shown when the user encouters an error
  • password_min_length (int) – Passwords must be at least this many characters long
  • password_allow_common (boolean) – Allow commonly used passwords
  • password_require_numeric (boolean) – Require users to have a number in their password
  • password_require_upper (boolean) – Require users to have an uppercase letter in their password
  • password_require_lower (boolean) – Require users to have an lowercase letter in their password
  • password_require_special (boolean) – Require users to have an special character (like ‘!@#$%’) in their password
  • password_expiration_days (int) – Require users to change their password after this number of days, 0=disabled
Request Headers:
 
  • Accept – the response content type depends on Accept header
  • Authorization – contains the token to be used for authentication
Response Headers:
 
Status Codes:

Get Site Details for a Client

GET /api/v1/jb/clients/(int: id)/site/

Get site details for a client

Example Request:

GET /api/v1/jb/clients/1/site/
Accept: application/json
Authorization: Token 7297b3ebb0e7f7baf5f54d39908dda99f5ea8665

Example Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "id": 2,
  "domain": "localhost:8000",
  "name": "localhost:8000"
}
Parameters:
  • id (int) – the id of the client
Response JSON Object:
 
  • id (int) – the id of the site
  • domain (string) – the domain name and optionally a port for the site
  • name (string) – the name of the site, which is often the same as the domain
Request Headers:
 
  • Accept – the response content type depends on Accept header
  • Authorization – contains the token to be used for authentication
Response Headers:
 
Status Codes:

Get a Client’s User List

GET /api/v1/jb/clients/(int: id)/users/

Get a details for a client

Example Request:

GET /api/v1/jb/clients/1/users/
Accept: application/json
Authorization: Token 7297b3ebb0e7f7baf5f54d39908dda99f5ea8665

Example Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

[
  {
    "extra": { },
    "last_login": "2016-06-01T13:34:30.718746Z",
    "email": "user@juice.com",
    "handle": "@user",
    "first_name": "User",
    "last_name": "User",
    "is_active": true,
    "date_joined": "2013-07-28T21:04:32Z",
    "is_demo_user": false,
    "profile_color": "ff0000",
    "profile_avatar": "https://fruition-snapshots.s3.amazonaws.com/avatars/profile-defaults/o.png",
    "last_activated": "2016-06-01T13:22:24.439209Z",
    "last_deactivated": null,
    "last_password_set": "2016-06-01T13:22:24.439209Z",
    "apps": [
      "zylTKNVx"
    ]
  }
]
Parameters:
  • id (int) – the id of the client
Response JSON Object:
 
  • extra (int) – extra data associated with the user for use in your apps
  • email (string) – the user’s email address
  • handle (string) – the user’s discussion handle
  • first_name (string) – the user’s first name
  • last_name (string) – the user’s last name
  • is_active (boolean) – the active status of the user
  • is_demo_user (boolean) – the demo status of the user
  • profile_color (string) – hex color code of the user’s profile
  • profile_avatar (string) – the user’s selected avatar
  • apps (array) – A list of app ids to which the user has access
  • last_login (date) – the last date the user logged into the system
  • date_joined (date) – the date the user was created
  • last_activated (date) – the date the user was last activated
  • last_deactivated (date) – the date the user was last deactivated
  • last_password_set (date) – the date the user last set their password
Request Headers:
 
  • Accept – the response content type depends on Accept header
  • Authorization – contains the token to be used for authentication
Response Headers:
 
Status Codes:

Get a Client’s Invited User List

GET /api/v1/jb/clients/(int: id)/users/invitations/

Get a list of pending invited users

Example Request:

GET /api/v1/jb/clients/1/users/invitations/
Accept: application/json
Authorization: Token 7297b3ebb0e7f7baf5f54d39908dda99f5ea8665

Example Response:

 HTTP/1.1 200 OK
 Vary: Accept
 Content-Type: text/javascript

[
   {
     "id": 3,
     "user": {
       "extra": {},
       "last_login": null,
       "email": "jason@juice.com",
       "handle": "@jason",
       "first_name": "",
       "last_name": "",
       "is_active": true,
       "date_joined": "2016-06-01T18:13:17.943920Z",
       "is_demo_user": false,
       "profile_color": "ff0000",
       "profile_avatar": "https://fruition-snapshots.s3.amazonaws.com/avatars/profile-defaults/default.png",
       "last_activated": "2016-06-01T18:13:17.943951Z",
       "last_deactivated": null,
       "apps": []
     },
     "initial_apps": [],
     "extra": {},
     "email": "invited_user@juiceanalytics.com",
     "key": "0626d808767dc0abc76a4266ad2df687b3008156",
     "date_invited": "2016-06-01T18:24:04.358609Z",
     "invitation_email_count": 1
   },
 ]
Parameters:
  • id (int) – the id of the client
Response JSON Object:
 
  • id (int) – the id of the invite
  • user (object) – the user who performed the invite
  • extra (int) – extra data associated with the user for use in your apps
  • email (string) – the invited user’s email address
  • key (string) – a unique key to identify the invited user
  • initial_apps (array) – A list of app ids to which the user has been invited
  • date_invited (date) – the date the user invited to join the system
  • invitation_email_count (int) – a counter to show how many times the user has been sent an invite
Request Headers:
 
  • Accept – the response content type depends on Accept header
  • Authorization – contains the token to be used for authentication
Response Headers:
 
Status Codes:

Invite a User to Join a Client

POST /api/v1/jb/clients/(int: id)/users/invitations/

Get a list of pending invited users

Example Request:

POST /api/v1/jb/clients/1/users/invitations/
Accept: application/json
Authorization: Token 7297b3ebb0e7f7baf5f54d39908dda99f5ea8665

{
  "email": "new_user@juiceanalytics.com",
  "extra": {},
  "initial_apps": [
    "zylTKNVx"
  ]
}

Example Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "id": 4,
  "user": {
    "extra": {},
    "last_login": null,
    "email": "jason@juice.com",
    "handle": "@jason",
    "first_name": "",
    "last_name": "",
    "is_active": true,
    "date_joined": "2016-06-01T18:13:17.943920Z",
    "is_demo_user": false,
    "profile_color": "ff0000",
    "profile_avatar": "https://fruition-snapshots.s3.amazonaws.com/avatars/profile-defaults/default.png",
    "last_activated": "2016-06-01T18:13:17.943951Z",
    "last_deactivated": null,
    "apps": []
  },
  "initial_apps": ["zylTKNVx",],
  "extra": {},
  "email": "new_user@juiceanalytics.com",
  "key": "0626d808767dc0abc76a4266ad2df687b3008156",
  "date_invited": "2016-06-01T18:24:04.358609Z",
  "invitation_email_count": 1
},
Parameters:
  • id (int) – the id of the client
Request JSON Object:
 
  • email (string) – the invited user’s email address
  • extra (object) – extra data associated with the user for use in your apps
  • initial_apps (array) – A list of app IDs to add to the invited user
Response JSON Object:
 
  • user (object) – the user who performed the invite
  • extra (int) – extra data associated with the user for use in your apps
  • email (string) – the invited user’s email address
  • key (string) – a unique key to identify the invited user
  • initial_apps (array) – A list of app details to which the user has been invited
  • date_invited (date) – the date the user invited to join the system
  • invitation_email_count (int) – a counter to show how many times the user has been sent an invite
Request Headers:
 
  • Accept – the response content type depends on Accept header
  • Authorization – contains the token to be used for authentication
Response Headers:
 
Status Codes:

Get a Client’s App List

GET /api/v1/jb/clients/(int: id)/apps/

Get a list of apps for a client

Example Request:

GET /api/v1/jb/clients/1/apps/
Accept: application/json
Authorization: Token 7297b3ebb0e7f7baf5f54d39908dda99f5ea8665

Example Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

[
  {
    "id": "zylTKNVx",
    "slug": "datademo",
    "label": "Data Services Demo",
    "show_help": false,
    "help_html": "\n",
    "show_footer": false,
    "footer_html": "",
    "description": "US Census Bureau data services demo"
  }
]
Parameters:
  • id (int) – the id of the client
Response JSON Object:
 
  • id (string) – the unique id of the application
  • slug (string) – a shortened name of the application
  • label (string) – The label or name of the application
  • description (string) – A short description of the app
  • help_html (string) – HTML to append to the built in help
  • footer_html (string) – HTML to show as the app footer
  • show_help (boolean) – should we show help in the app
  • show_footer (boolean) – should we show a footer in the app
Request Headers:
 
  • Accept – the response content type depends on Accept header
  • Authorization – contains the token to be used for authentication
Response Headers:
 
Status Codes: