Skip to content

Latest commit

 

History

History
2594 lines (2392 loc) · 72.8 KB

API.md

File metadata and controls

2594 lines (2392 loc) · 72.8 KB

The Morphic Lite API

Endpoints

User Registration

/v1/register/username   Marked for deprecation  

POST   Marked for deprecation  

Create a new user with empty preferences and the ability to login with the given username/password credentials.

Immediately log the user in and return an authentication token.

Headers
Content-Type application/json; charset=utf-8 Required
Request Body
username The user-chosen username String Required
password The user-chosen password String Required
email The user's email String Required
first_name The user's first name String Optional
last_name The user's last name String Optional
200 Response Body
token The token string to use in the Authorization header String Required
user The user object User Required
400 Response Body
error Missing required fields "missing_required"
Username already exists "existing_username"
Email already exists "existing_email"
Email is Malformed "malformed_email"
Known bad password "bad_password"
Password is too short "short_password"
details Specific error details object Optional
    .minimum_length short_password minimum password length Number Required
    .required missing_required list of missing field names string[] Required

/v1/register/key (Disabled)   Marked for deprecation  

Temporarily disabled until we need it

POST   Marked for deprecation  

Create a new user with empty preferences and the ability to login with the given secret key credentials.

Immediately log the user in and return an authentication token.

Headers
Content-Type application/json; charset=utf-8 Required
Request Body
key The client-derived secret key String Required
first_name The user's first name String Optional
last_name The user's last name String Optional
200 Response Body
token The token string to use in the Authorization header String Required
user The user object User Required
400 Response Body
error Missing required fields "missing_required"
Key already exists "existing_key"
details Specific error details object Optional
    .required missing_required list of missing field names string[] Required

/v1/invitations/{id}

GET

Get the details of an invitation to show a custom user registration or login screen.

The personal information returned can be used to pre-fill a user registration form.

After the user is registered or authenticated, complete the invitation process by POSTing to the /v1/community/{cid}/invitations/{id}/accept endpoint.

Headers
200 Response Body
community The community the user was invited to object Required
    .id The community's id String Required
    .name The community's name String Required
email The invitee's email String Required
first_name The invitee's first name String Optional
last_name The invitee's last name String Optional

Authentication

/v1/auth/username   Marked for deprecation  

POST   Marked for deprecation  

Authenticate the given username/password credentials and return a token that can be used in Authorization headers.

Headers
Content-Type application/json; charset=utf-8 Required
Request Body
username The username to authenticate String Required
password The password to authenticate for the username String Required
200 Response Body
token The token string to use in the Authorization header String Required
user The user object User Required
400 Response Body
error Invalid credentials, including missing fields "invalid_credentials"
Account is temporarily locked "locked"
Rate limit exceeded "rate_limited"
details Specific error details object Optional
    .timeout locked duration in seconds until unlocked Number Required

/v1/auth/token   Marked for deprecation  

DELETE   Marked for deprecation  

Deletes the auth token. Used when logging out of the app.

Headers
Content-Type application/json; charset=utf-8 Required
Request Body
204 Response Body

/v1/auth/key (Disabled)   Marked for deprecation  

Temporarily disabled until we need it

POST   Marked for deprecation  

Authenticate the given secret key credentials and return a token that can be used in Authorization headers.

Headers
Content-Type application/json; charset=utf-8 Required
Request Body
key The secret key to authenticate String Required
200 Response Body
token The token string to use in the Authorization header String Required
user The user object User Required
400 Response Body
error Invalid credentials, including missing fields "invalid_credentials"
Rate limit exceeded "rate_limited"

User Data

/v1/users/{id}   Marked for deprecation  

GET   Marked for deprecation  

Get the user object for the given id

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
id The user's unique ID String Required
preferences_id The ID for the user's preferences String Required
first_name The user's first name String Optional
last_name The user's last name String Optional
401 Response Headers
WWW-Authenticate Bearer Required
401 Response Body
Empty indicates authentication required
403 Response Body
Empty indicates unauthorized, regardless of whether the requested record actually exists

PUT   Marked for deprecation  

Save the user object for the given id

Headers
Content-Type application/json; charset=utf-8 Required
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
Request Body
first_name The user's first name String Optional
last_name The user's last name String Optional
200 Response Body
Empty indicates success
401 Response Headers
WWW-Authenticate Bearer Required
401 Response Body
Empty indicates authentication required
403 Response Body
Empty indicates unauthorized, regardless of whether the requested record actually exists

/v1/users/{uid}/preferences/{id}   Marked for deprecation  

A preference id can be found in the preferences_id property of a user object.

GET   Marked for deprecation  

Get the preferences object for the given id.

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
id The preferences unique ID String Required
user_id The ID for the user that owns the preferences String Required
default The dictionary of solution-specific preferences. The keys are solution identifiers. Each solution can have a completely arbitrary object for its preferences. {String: Object} Optional
401 Response Headers
WWW-Authenticate Bearer Required
401 Response Body
Empty indicates authentication required
403 Response Body
Empty indicates unauthorized, regardless of whether the requested record actually exists
404 Response Body
Empty indicates invalid preferences id

PUT   Marked for deprecation  

Save the user object for the given id

Headers
Content-Type application/json; charset=utf-8 Required
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
Request Body
default The dictionary of solution-specific preferences. The keys are solution identifiers. Each solution can have a completely arbitrary object for its preferences. {String: Object} Required
200 Response Body
Empty indicates success
401 Response Headers
WWW-Authenticate Bearer Required
401 Response Body
Empty indicates authentication required
403 Response Body
Empty indicates unauthorized, regardless of whether the requested record actually exists
404 Response Body
Empty indicates invalid preferences id

/v1/users/{userId}/password

POST

Change the password of an authenticated user. Providing the old password is required for additional security.

Headers
Content-Type application/json; charset=utf-8 Required
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
Request Body
existing_password The existing password String Required
new_password The new password to set String Required
delete_existing_tokens Delete any existing Auth Tokens Boolean Optional
200 Response Body
Empty indicates success
400 Response Body
error Missing required fields "missing_required"
Username already exists "existing_username"
Invalid credentials "invalid_credentials"
Rate limit exceeded "rate_limited"

/v1/users/{id}/communities   Marked for deprecation  

GET   Marked for deprecation  

Get a list of communities the user belongs to.

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
communities The communities the user belongs to Array Required
    [i].id The community unique identifier string Required
    [i].name The community display name string Required
    [i].role The role the user has in the community Role Required
    [i].member_id The user's member id for the community GUID Required

Role: String

  • manager
  • member

/v1/users/{uid}/communities/{id}   Marked for deprecation  

GET   Marked for deprecation  

The details of a community the user belongs to

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
id The community unique identifier string Required
name The community display name string Required
bar The bar to show for this user object Required
    .id The bar's id string Required
    .name The bar's name string Required
    .items The items shown on the bar Array Required
        [i].kind The bar item's type BarItemKind Required
        [i].is_primary Whether the item should be displayed on the primary bar Boolean Required
        [i].configuration The bar item's configuration, depending on its kind object Optional
400 Response Body
error The community is locked, possibly because of a payment problem "community_locked"

BarItemKind: String

  • link
  • application
  • action

/v1/users/{id}/unregister

POST

Create a new user with empty preferences and the ability to login with the given username/password credentials.

Immediately log the user in and return an authentication token.

Headers
Content-Type application/json; charset=utf-8 Required
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
Empty indicates authentication required
403 Response Body
Empty indicates unauthorized, regardless of whether the requested record actually exists

/v1/users/{id}/resend_verification

POST

Re-send the user's verification email.

Headers
Content-Type application/json; charset=utf-8 Required
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
Empty indicates success

Password Reset

/v1/auth/username/password_reset/{oneTimeToken}

POST

Reset a password

Headers
Content-Type application/json; charset=utf-8 Required
Request Body
new_password The new password String Required
delete_existing_tokens Whether to terminate all existing auth sessions immediately. Boolean Optional (default: false)
200 Response Body
Empty indicates success
400 Response Body
error Missing required fields "missing_required"
Invalid One-Time Token "invalid_token"
User Not found "invalid_user"
details Specific error details object Optional
    .required missing_required list of missing field names string[] Required

/v1/auth/username/password_reset/request

POST

Request a password reset email.

Headers
Content-Type application/json; charset=utf-8 Required
Request Body
email Email to send the password reset email to. String Required
g_recaptcha_response The recaptcha response from the UI String Required
200 Response Body
Empty indicates success
400 Response Body
error Malformed email address "bad_email_address"
Bad Recaptcha "bad_recaptcha"
details Specific error details object Optional
    .required missing_required list of missing field names string[] Required

Community

/v1/communities

POST

Create a new community

Headers
Content-Type application/json; charset=utf-8 Required
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
Request Body
name The new community name String Required
200 Response Body
community The newly created community Community Required
400 Response Body
error Missing required fields "missing_required"
details Specific error details object Optional
    .required missing_required list of missing field names string[] Required

/v1/communities/{id}

GET

Get a community's details

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
id The community id String Required
name The new community name String Required
default_bar_id
  Deprecated  		 The default bar for this community String Required
member_count The number of members in the community that count towards the plan maximum int Required
member_limit The maximum number of members allowed according to the plan int Required
is_locked Indicates the community is locked because of payment issues Boolean Required

PUT

Update a community

Headers
Content-Type application/json; charset=utf-8 Required
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
Request Body
name The new community name String Required
default_bar_id
  Deprecated  		 The new default bar id for this community String Required
200 Response Body
Empty indicates success
400 Response Body
error Missing required fields "missing_required"
The Bar ID given could not be found "bad_bar_id"
details Specific error details object Optional
    .required missing_required list of missing field names string[] Required

DELETE

Delete a community

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
Empty indicates success

/v1/communities/{id}/members

GET

Get a list of community members

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
members The members for this page of results Array Required
    [i].id The member's unique id String Required
    [i].first_name The member's first name String Optional
    [i].last_name The member's last name String Optional
    [i].role The member's role Role Required
    [i].state The member's state State Required
    [i].bar_id
  Removed  		 The member's bar_id (null means use community default_bar_id) String Optional
    [i].bar_ids
  New  		 The member's bar_ids (an empty set means no bars) string[] Required

POST

Create a new community member

Headers
Content-Type application/json; charset=utf-8 Required
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
Request Body
first_name The member's first name String Optional
last_name The member's last name String Optional
200 Response Body
member The newly created member Member Required
400 Response Body
error Missing required fields "missing_required"
Member Limit reached for current plan "limit_reached"
details Specific error details object Optional
    .required missing_required list of missing field names string[] Required

/v1/communities/{cid}/members/{id}

GET

Get a community member's details

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
id The member's unique id String Required
first_name The member's first name String Optional
last_name The member's last name String Optional
role The member's role Role Required
state The member's state State Required
bar_id
  Removed  		 The member's bar, if not the community's default String Optional
bar_ids
  New  		 The member's bar_ids (an empty set means no bars) string[] Required

Role: String

  • manager
  • member

State: String

  • uninvited - Added, but not yet invited; still configuring
  • invited - Invitation sent, but not accepted
  • active - Invitation accepted

PUT

Update a community member's details

Headers
Content-Type application/json; charset=utf-8 Required
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
Request Body
first_name The member's first name String Optional
last_name The member's last name String Optional
bar_id
  Removed  		 The member's bar, if not the community's default String Optional
bar_ids
  New  		 The member's bar_ids (an empty set means no bars) string[] Required
role The member's role Role Required
200 Response Body
Empty indicates success
400 Response Body
error Missing required fields "missing_required"
Bar could not be found "bad_bar_id"
Cannot demote self from manager role "cannot_demote_self"
details Specific error details object Optional
    .required missing_required list of missing field names string[] Required

DELETE

Delete a member from a community

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
Empty indicates success
400 Response Body
error Cannot delete self "cannot_delete_self"

/v1/communities/{id}/invitations

POST

Send a new invitation for a community member

Headers
Content-Type application/json; charset=utf-8 Required
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
Request Body
member_id The member's unique identifier String Required
email The member's email address, if not already added String Required
message A custom message that will be included in the email String Optional
200 Response Body
Empty indicates success
400 Response Body
error Missing required fields "missing_required"
Invalid Email Address "malformed_email"
Member not found "member_not_found"
Active Member "member_active"
Manager Email Verification Required "email_verification_required"
details Specific error details object Optional
    .required missing_required list of missing field names string[] Required

/v1/communities/{cid}/invitations/{id}/accept

POST

Accept an invitation

Headers
Content-Type application/json; charset=utf-8 Required
200 Response Body
Empty indicates success

/v1/communities/{id}/bars

GET

Get the list of bar configurations for the community

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
bars The list of bars Array Required
    [i].id The bar's unique id String Required
    [i].name The bar's display name String Required
    [i].is_shared Whether the bar is shown in the list of preconfigured bars that can be shared across multiple users Boolean Required

POST

Create a new bar configuration for the community

Headers
Content-Type application/json; charset=utf-8 Required
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
Request Body
name The bar's name String Required
is_shared Whether the bar is shown in the list of preconfigured bars that can be shared across multiple users Boolean Required
items The bar's items Array Required
    [i].kind The bar item's type BarItemKind Required
    [i].is_primary If the item should be shown on the primary bar Boolean Required
    [i].configuration The bar item's configuration, depending on its kind object Optional
200 Response Body
bar The newly created bar Bar Required
400 Response Body
error Missing required fields "missing_required"
details Specific error details object Optional
    .required missing_required list of missing field names string[] Required

/v1/communities/{cid}/bars/{id}

GET

Get the details of a particular bar

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
id The bar's unique id String Required
name The bar's display name String Required
is_shared Whether the bar is shown in the main bar list Boolean Required
items The bar's items Array Required
    [i].kind The bar item's type BarItemKind Required
    [i].is_primary If the item is shown on the primary bar Boolean Required
    [i].configuration The bar item's configuration, depending on its kind object Optional

BarItemKind: String

  • link (uses LinkConfiguration for configuration)
  • application (uses ApplicationConfiguration for configuration)
  • action (uses ActionConfiguration for configuration)

Bar Item configuration types

ButtonConfiguration: object{
  # The user-visible text shown on the button 
  label: string

  # RRGGBB hex string with leading "#"
  color: string?

  # The user-visible image shown on the button
  # Absolute URL for custom uploaded images (e.g., "http://bucket.s3/path/to/image")
  # Filename (relative url) for client-bundled icons (e.g., "video")
  image_url: string?
}

LinkConfiguration: ButtonConfiguration{
  # The url that should open as the result of clicking the button
  url: string

  # The subkind of link
  # Meaningful for showing the appropriate editor UI in the web client
  # Not used by the desktop client
  # Values determined by the web client, but might be strings like "skype" or "zoom"
  subkind: String?
}

ApplicationConfiguration: ButtonConfiguration{
  # Indicates the button should open the OS-default application of the given type
  # Possible values include:
  # - email
  # - calendar
  # - browser
  default: string?

  # The name or full path of the windows exe to open
  # (names are looked up in the registry HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths)
  exe: string?
}

ActionConfiguration: object{
  # The action identifier
  identifier: string

  # RRGGBB hex string with leading "#"
  color: string?
}

PUT

Update a bar's configuration

Headers
Content-Type application/json; charset=utf-8 Required
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
Request Body
name The bar's display name String Required
items The bar's items Array Required
    [i].kind The bar item's type BarItemKind Required
    [i].is_primary If the item should be shown on the primary bar Boolean Required
    [i].configuration The bar item's configuration, depending on its kind object Optional
200 Response Body
Empty indicates success
400 Response Body
error Missing required fields "missing_required"
Cannot un-share the community's default bar "default_must_be_shared"
details Specific error details object Optional
    .required missing_required list of missing field names string[] Required

DELETE

Delete a bar configuration

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
Empty indicates success
400 Response Body
error Cannot delete the communitie's default bar "cannot_delete_default"
error Cannot delete a bar that is in use "cannot_delete_used"

/v1/communities/{id}/skype/meetings

GET

Proxy for https://api.join.skype.com/v1/meetnow/createjoinlinkguest, which enforces CORS restrictions on browser-based requests.

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
Request Body
Title The title for the new meeting String Required
200 Response Body
joinLink The url of the new skype meeting String Required

/v1/communities/{id}/billing

GET

Get the billing information for a community

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
plan_id The community plan String Required
trial_end The date/time, in ISO 8601 format, of the end of the trial period String Required
status Payment status PaymentStatus Required
contact_member_id The ID of the member who is the billing contact String Required
card An object representing the credit card on file object Optional
    .brand The brand of the card String Required
    .last4 The last four digits of the card String Required

PaymentStatus: String

  • paid - All payments have been made (or still in trial)
  • past_due - Payments have failed, but retries have not been exhausted
  • canceled - User canceled their account, but it won't close until the end of the billing cycle
  • closed - Account is closed due to user request or lack of payment

PUT

Update the billing information for a community

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
Request Body
plan_id The community plan String Required
contact_member_id The ID of the member who is the billing contact String Required
200 Response Body
Empty indicates success
400 Response Body
error Invalid plan "bad_plan_id"
Invalid contact "bad_member_id"
The chosen plan's member limit smaller than the community's member count "plan_limit_exceeded"

/v1/communities/{id}/billing/card

POST

Update the card used for billing

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
Request Body
token The stripe card token id String Required
200 Response Body
card An object representing the credit card on file object Optional
    .brand The brand of the card String Required
    .last4 The last four digits of the card String Required
400 Response Body
error The card could not be validated "invalid"

/v1/communities/{id}/billing/cancel

POST

Cancel the account at the end of the billing period

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 Response Body
billing The updated billing record Billing Required

Plans

/v1/plans/community

GET

Get the list of active billing plans for Morphic Community

Headers
Content-Type application/json; charset=utf-8 Required
200 Response Body
plans The list of active community plans Array Required
    [i].id The plan's unique ID String Required
    [i].member_limit The number of members allowed under the plan int Required
    [i].months The number of months in the plan's billing cycle int Required
    [i].price The price in the currency's smallest denomination (e.g., cent for USD) int Required
    [i].currency The currency of the price int Required
    [i].price_text The price, for displaying String Required
    [i].monthly_price_text The monthly price, for displaying. Used to compare the monthly cost with other plans. String Required

Link Validation

/v1/validate/link/{url}

HEAD

Validates a link. Used by the web client to check if a link is valid for a button.

({url} should be URL-encoded)

Headers
Authorization "Bearer " + Token string obtained from/auth/username or /auth/key Required
200 (No Response Body)
The link works.
410 (No Response Body)
The link does not work.