Top contributors

Origami

Top contributors

Checkpoint

Checkpoint is a centralized authentication broker for web applications that supports a number of authentication mechanisms via an http interface. Checkpoint can take care of logging your users into your application and keep track of session and access privileges across services.

Concepts

Realm - The security context for your application. A given session is valid for a specific realm. Realms may span any number of services, but they should ideally be construed as a single coherent 'brand' in the mind of your users. An example realm could be "google" where all the services provided within the 'google' realm shared identities across services.

Domain - A realm is connected to a number of domains (e.g. 'google' realm could be attached to the domains 'maps.google.com' and 'reader.google.com' and even 'youtube.com'). Checkpoint looks at the current host domain to determine the current realm when e.g. logging a user in.

Identity - Represents one specific person. An identity may have a number of accounts.

Account - A verified account with a specific provider that can be used to log in to a specific identity.

Basic config

Checkpoint is provided as an http service and needs to be mapped into the url-space of your application using some proxy mechanism. The standard root url for checkpoint is:

/api/checkpoint/v1/

In production this mapping is done with ha-proxy. In development a rack proxy will be provided.

Typical usage

Given that your basic config is set up, your user can log in by being sent to the appropriate login action. A "Log in with Twitter" link should direct the browser to the following url:

/api/checkpoint/v1/login/twitter

An authentication process will commence possibly taking your user via twitter to confirm their identity. If login is successful your user is returned to your application at:

/login/succeeded

The session key for the logged in user is now stored in the cookie named 'checkpoint.session'. This is a 512 bit hash that can be used with all Pebble-compliant web-services to identify your current user and her credentials. (Unsuccessful logins are returned to: /login/failed)

Currently Checkpoint supports the following authentication mechanisms:

Twitter

Facebook

Google

Origo

Sessions

The basic purpose of Checkpoint is providing and managing sessions for your users. A session in Checkpoint is represented by a 512 bit string of random garbage, the 'session string'. This string can be passed around to all pebbles compliant web services as proof of identity.

To check the identity for a specific session, this call to checkpoint could be used:

Pebbles expect to find the session string in one of two places. First it looks for a url-parameter named 'session', if it is not found there it will attempt to retrieve it from a cookie named 'checkpoint.session'. If neither of these are present the request will be processed without authentication.

Fingerprinting

For each account registered with an identity, one or more fingerprints are recorded for posterity based on the account information. The fingerprint is an SHA-256 hash computed from the immutable parts of the account information, such as one's Twitter UID, mobile number or similar.

The fingerprint obscures the original details but still permits the application to determine if a future credential has been fingerprinted, thus making it possible to ban Twitter users, mobile numbers, etc. without having the original information at hand.

Checkpoint exposes an API that can be used to check for banned fingerprints. This API uses the Pebblebed path system, so that the banning system can be used not only for blocking logins, but for fine-grained access control such as blocking users from posting in a forum.

Callbacks

Pebbles have default rules guarding who gets to do what to a given object. Callbacks allow implementation of custom policies for creating, updating and deleting objects.

A callback is registered with a path and an url. If a callback is registered with the path 'a.b.c' it will be consulted for any action within that path, i.e. it will be called when someone wants to update post:a.b.c.d.e.f.g$11 or post:a.b.c$1, but not post:a$1or post:z.y.x$666.

When a pebble consults checkpoint to determine if an action should be allowed, the callback will post to the url. The post will recieve the parameters method, uid and identity. method will be either 'create', 'update' or 'delete', uid is the uid of the object the action will be taken on, identity is the id of the identity attempting to perform the action. The callback should return a json-hash with the key allowed. If the action should be allowed, allowed should be true, if it should be denied: false. If the callback does not have a specific opinion on the matter it should respond with an empty hash. If the callback chooses to deny the action, it should provide a reason in the response hash. This is a human readable string that may be presented to a user.

At the time of writing, only Grove actually consults checkpoint callbacks. In the future all pebbles must support this. To support callbacks, a pebble must GET /callbacks/allowed/:method/:uid before performing the action. The allowed key in the response will be either true, false or default. true means 'categorically allowed, override default behavior', false means 'categorically' denied, while default means 'apply internal rules, the callbacks had nothing to say about this'. Typically this means no callback was defined for the path in question. If the action has been denied, the response will also include the url of the denying callback along with a textual reason for the denial.

Tagging

Identities support arbitrary sets of tags. (A tag can be any string, including spaces.) The main use case is to allow apps to tag the origin of identities when there may be multiple applications sharing the same realm.

For example, if you develop apps A and B, and these apps tag their identities accordingly, then it's trivial to determine which identities came from which app. If, say, app B is discontinued or must be moved to a separate realm, it's easy to purge/move the identities if they have been tagged correctly.

Tagging is entirely-freeform and can serve any purpose, however.

Custom strategy and provider

A customized installation of Checkpoint might need to implement its own provider and strategy for authentication against an existing user/password store. Refer to config/strategies-example.rb and the checkpoint-strategy gem to set up a Checkpoint compliant provider and strategy.

Known weaknesses

The service defines a critical single point of failure. Infrastructure should be put in place for a redundant solution – either a high-availability memcached cluster or a different key-value store.

The members of the group will be able to read all restricted content
within the paths added to the group. I.e. if the path 'acme.secrets' is
added to the group 'secret_cabal', its members will be able to read the secrets
that are posted with the restricted flag within this path. This would include
'post.secret_dossier:acme.secrets.top_secret.sinister_plans$3241'.

Checkpoint

Checkpoint is a centralized authentication broker for web applications that supports a number of authentication mechanisms via an http interface. Checkpoint can take care of logging your users into your application and keep track of session and access privileges across services.

Concepts

Realm - The security context for your application. A given session is valid for a specific realm. Realms may span any number of services, but they should ideally be construed as a single coherent 'brand' in the mind of your users. An example realm could be "google" where all the services provided within the 'google' realm shared identities across services.

Domain - A realm is connected to a number of domains (e.g. 'google' realm could be attached to the domains 'maps.google.com' and 'reader.google.com' and even 'youtube.com'). Checkpoint looks at the current host domain to determine the current realm when e.g. logging a user in.

Identity - Represents one specific person. An identity may have a number of accounts.

Account - A verified account with a specific provider that can be used to log in to a specific identity.

Basic config

Checkpoint is provided as an http service and needs to be mapped into the url-space of your application using some proxy mechanism. The standard root url for checkpoint is:

/api/checkpoint/v1/

In production this mapping is done with ha-proxy. In development a rack proxy will be provided.

Typical usage

Given that your basic config is set up, your user can log in by being sent to the appropriate login action. A "Log in with Twitter" link should direct the browser to the following url:

/api/checkpoint/v1/login/twitter

An authentication process will commence possibly taking your user via twitter to confirm their identity. If login is successful your user is returned to your application at:

/login/succeeded

The session key for the logged in user is now stored in the cookie named 'checkpoint.session'. This is a 512 bit hash that can be used with all Pebble-compliant web-services to identify your current user and her credentials. (Unsuccessful logins are returned to: /login/failed)

Currently Checkpoint supports the following authentication mechanisms:

Twitter

Facebook

Google

Origo

Sessions

The basic purpose of Checkpoint is providing and managing sessions for your users. A session in Checkpoint is represented by a 512 bit string of random garbage, the 'session string'. This string can be passed around to all pebbles compliant web services as proof of identity.

To check the identity for a specific session, this call to checkpoint could be used:

Pebbles expect to find the session string in one of two places. First it looks for a url-parameter named 'session', if it is not found there it will attempt to retrieve it from a cookie named 'checkpoint.session'. If neither of these are present the request will be processed without authentication.

Fingerprinting

For each account registered with an identity, one or more fingerprints are recorded for posterity based on the account information. The fingerprint is an SHA-256 hash computed from the immutable parts of the account information, such as one's Twitter UID, mobile number or similar.

The fingerprint obscures the original details but still permits the application to determine if a future credential has been fingerprinted, thus making it possible to ban Twitter users, mobile numbers, etc. without having the original information at hand.

Checkpoint exposes an API that can be used to check for banned fingerprints. This API uses the Pebblebed path system, so that the banning system can be used not only for blocking logins, but for fine-grained access control such as blocking users from posting in a forum.

Callbacks

Pebbles have default rules guarding who gets to do what to a given object. Callbacks allow implementation of custom policies for creating, updating and deleting objects.

A callback is registered with a path and an url. If a callback is registered with the path 'a.b.c' it will be consulted for any action within that path, i.e. it will be called when someone wants to update post:a.b.c.d.e.f.g$11 or post:a.b.c$1, but not post:a$1or post:z.y.x$666.

When a pebble consults checkpoint to determine if an action should be allowed, the callback will post to the url. The post will recieve the parameters method, uid and identity. method will be either 'create', 'update' or 'delete', uid is the uid of the object the action will be taken on, identity is the id of the identity attempting to perform the action. The callback should return a json-hash with the key allowed. If the action should be allowed, allowed should be true, if it should be denied: false. If the callback does not have a specific opinion on the matter it should respond with an empty hash. If the callback chooses to deny the action, it should provide a reason in the response hash. This is a human readable string that may be presented to a user.

At the time of writing, only Grove actually consults checkpoint callbacks. In the future all pebbles must support this. To support callbacks, a pebble must GET /callbacks/allowed/:method/:uid before performing the action. The allowed key in the response will be either true, false or default. true means 'categorically allowed, override default behavior', false means 'categorically' denied, while default means 'apply internal rules, the callbacks had nothing to say about this'. Typically this means no callback was defined for the path in question. If the action has been denied, the response will also include the url of the denying callback along with a textual reason for the denial.

Tagging

Identities support arbitrary sets of tags. (A tag can be any string, including spaces.) The main use case is to allow apps to tag the origin of identities when there may be multiple applications sharing the same realm.

For example, if you develop apps A and B, and these apps tag their identities accordingly, then it's trivial to determine which identities came from which app. If, say, app B is discontinued or must be moved to a separate realm, it's easy to purge/move the identities if they have been tagged correctly.

Tagging is entirely-freeform and can serve any purpose, however.

Custom strategy and provider

A customized installation of Checkpoint might need to implement its own provider and strategy for authentication against an existing user/password store. Refer to config/strategies-example.rb and the checkpoint-strategy gem to set up a Checkpoint compliant provider and strategy.

Known weaknesses

The service defines a critical single point of failure. Infrastructure should be put in place for a redundant solution – either a high-availability memcached cluster or a different key-value store.

Checkpoint

Checkpoint is a centralized authentication broker for web applications that supports a number of authentication mechanisms via an http interface. Checkpoint can take care of logging your users into your application and keep track of session and access privileges across services.

Concepts

Realm - The security context for your application. A given session is valid for a specific realm. Realms may span any number of services, but they should ideally be construed as a single coherent 'brand' in the mind of your users. An example realm could be "google" where all the services provided within the 'google' realm shared identities across services.

Domain - A realm is connected to a number of domains (e.g. 'google' realm could be attached to the domains 'maps.google.com' and 'reader.google.com' and even 'youtube.com'). Checkpoint looks at the current host domain to determine the current realm when e.g. logging a user in.

Identity - Represents one specific person. An identity may have a number of accounts.

Account - A verified account with a specific provider that can be used to log in to a specific identity.

Basic config

Checkpoint is provided as an http service and needs to be mapped into the url-space of your application using some proxy mechanism. The standard root url for checkpoint is:

/api/checkpoint/v1/

In production this mapping is done with ha-proxy. In development a rack proxy will be provided.

Typical usage

Given that your basic config is set up, your user can log in by being sent to the appropriate login action. A "Log in with Twitter" link should direct the browser to the following url:

/api/checkpoint/v1/login/twitter

An authentication process will commence possibly taking your user via twitter to confirm their identity. If login is successful your user is returned to your application at:

/login/succeeded

The session key for the logged in user is now stored in the cookie named 'checkpoint.session'. This is a 512 bit hash that can be used with all Pebble-compliant web-services to identify your current user and her credentials. (Unsuccessful logins are returned to: /login/failed)

Currently Checkpoint supports the following authentication mechanisms:

Twitter

Facebook

Google

Origo

Sessions

The basic purpose of Checkpoint is providing and managing sessions for your users. A session in Checkpoint is represented by a 512 bit string of random garbage, the 'session string'. This string can be passed around to all pebbles compliant web services as proof of identity.

To check the identity for a specific session, this call to checkpoint could be used:

Pebbles expect to find the session string in one of two places. First it looks for a url-parameter named 'session', if it is not found there it will attempt to retrieve it from a cookie named 'checkpoint.session'. If neither of these are present the request will be processed without authentication.

Fingerprinting

For each account registered with an identity, one or more fingerprints are recorded for posterity based on the account information. The fingerprint is an SHA-256 hash computed from the immutable parts of the account information, such as one's Twitter UID, mobile number or similar.

The fingerprint obscures the original details but still permits the application to determine if a future credential has been fingerprinted, thus making it possible to ban Twitter users, mobile numbers, etc. without having the original information at hand.

Checkpoint exposes an API that can be used to check for banned fingerprints. This API uses the Pebblebed path system, so that the banning system can be used not only for blocking logins, but for fine-grained access control such as blocking users from posting in a forum.

Callbacks

Pebbles have default rules guarding who gets to do what to a given object. Callbacks allow implementation of custom policies for creating, updating and deleting objects.

A callback is registered with a path and an url. If a callback is registered with the path 'a.b.c' it will be consulted for any action within that path, i.e. it will be called when someone wants to update post:a.b.c.d.e.f.g$11 or post:a.b.c$1, but not post:a$1or post:z.y.x$666.

When a pebble consults checkpoint to determine if an action should be allowed, the callback will post to the url. The post will recieve the parameters method, uid and identity. method will be either 'create', 'update' or 'delete', uid is the uid of the object the action will be taken on, identity is the id of the identity attempting to perform the action. The callback should return a json-hash with the key allowed. If the action should be allowed, allowed should be true, if it should be denied: false. If the callback does not have a specific opinion on the matter it should respond with an empty hash. If the callback chooses to deny the action, it should provide a reason in the response hash. This is a human readable string that may be presented to a user.

At the time of writing, only Grove actually consults checkpoint callbacks. In the future all pebbles must support this. To support callbacks, a pebble must GET /callbacks/allowed/:method/:uid before performing the action. The allowed key in the response will be either true, false or default. true means 'categorically allowed, override default behavior', false means 'categorically' denied, while default means 'apply internal rules, the callbacks had nothing to say about this'. Typically this means no callback was defined for the path in question. If the action has been denied, the response will also include the url of the denying callback along with a textual reason for the denial.

Tagging

Identities support arbitrary sets of tags. (A tag can be any string, including spaces.) The main use case is to allow apps to tag the origin of identities when there may be multiple applications sharing the same realm.

For example, if you develop apps A and B, and these apps tag their identities accordingly, then it's trivial to determine which identities came from which app. If, say, app B is discontinued or must be moved to a separate realm, it's easy to purge/move the identities if they have been tagged correctly.

Tagging is entirely-freeform and can serve any purpose, however.

Custom strategy and provider

A customized installation of Checkpoint might need to implement its own provider and strategy for authentication against an existing user/password store. Refer to config/strategies-example.rb and the checkpoint-strategy gem to set up a Checkpoint compliant provider and strategy.

Known weaknesses

The service defines a critical single point of failure. Infrastructure should be put in place for a redundant solution – either a high-availability memcached cluster or a different key-value store.

Some applications require the user to perform actions that need an identity,
but still do not require any authenitcation. Redirect the users browser here to get an
anonymous user session. The identity will be a valid checkpoint identity with no accounts
or profile.

Parameter

Type

Description

redirect_to

String

Where to redirect the user after login (NOTE: required if non-xhr request).

Checkpoint

Checkpoint is a centralized authentication broker for web applications that supports a number of authentication mechanisms via an http interface. Checkpoint can take care of logging your users into your application and keep track of session and access privileges across services.

Concepts

Realm - The security context for your application. A given session is valid for a specific realm. Realms may span any number of services, but they should ideally be construed as a single coherent 'brand' in the mind of your users. An example realm could be "google" where all the services provided within the 'google' realm shared identities across services.

Domain - A realm is connected to a number of domains (e.g. 'google' realm could be attached to the domains 'maps.google.com' and 'reader.google.com' and even 'youtube.com'). Checkpoint looks at the current host domain to determine the current realm when e.g. logging a user in.

Identity - Represents one specific person. An identity may have a number of accounts.

Account - A verified account with a specific provider that can be used to log in to a specific identity.

Basic config

Checkpoint is provided as an http service and needs to be mapped into the url-space of your application using some proxy mechanism. The standard root url for checkpoint is:

/api/checkpoint/v1/

In production this mapping is done with ha-proxy. In development a rack proxy will be provided.

Typical usage

Given that your basic config is set up, your user can log in by being sent to the appropriate login action. A "Log in with Twitter" link should direct the browser to the following url:

/api/checkpoint/v1/login/twitter

An authentication process will commence possibly taking your user via twitter to confirm their identity. If login is successful your user is returned to your application at:

/login/succeeded

The session key for the logged in user is now stored in the cookie named 'checkpoint.session'. This is a 512 bit hash that can be used with all Pebble-compliant web-services to identify your current user and her credentials. (Unsuccessful logins are returned to: /login/failed)

Currently Checkpoint supports the following authentication mechanisms:

Twitter

Facebook

Google

Origo

Sessions

The basic purpose of Checkpoint is providing and managing sessions for your users. A session in Checkpoint is represented by a 512 bit string of random garbage, the 'session string'. This string can be passed around to all pebbles compliant web services as proof of identity.

To check the identity for a specific session, this call to checkpoint could be used:

Pebbles expect to find the session string in one of two places. First it looks for a url-parameter named 'session', if it is not found there it will attempt to retrieve it from a cookie named 'checkpoint.session'. If neither of these are present the request will be processed without authentication.

Fingerprinting

For each account registered with an identity, one or more fingerprints are recorded for posterity based on the account information. The fingerprint is an SHA-256 hash computed from the immutable parts of the account information, such as one's Twitter UID, mobile number or similar.

The fingerprint obscures the original details but still permits the application to determine if a future credential has been fingerprinted, thus making it possible to ban Twitter users, mobile numbers, etc. without having the original information at hand.

Checkpoint exposes an API that can be used to check for banned fingerprints. This API uses the Pebblebed path system, so that the banning system can be used not only for blocking logins, but for fine-grained access control such as blocking users from posting in a forum.

Callbacks

Pebbles have default rules guarding who gets to do what to a given object. Callbacks allow implementation of custom policies for creating, updating and deleting objects.

A callback is registered with a path and an url. If a callback is registered with the path 'a.b.c' it will be consulted for any action within that path, i.e. it will be called when someone wants to update post:a.b.c.d.e.f.g$11 or post:a.b.c$1, but not post:a$1or post:z.y.x$666.

When a pebble consults checkpoint to determine if an action should be allowed, the callback will post to the url. The post will recieve the parameters method, uid and identity. method will be either 'create', 'update' or 'delete', uid is the uid of the object the action will be taken on, identity is the id of the identity attempting to perform the action. The callback should return a json-hash with the key allowed. If the action should be allowed, allowed should be true, if it should be denied: false. If the callback does not have a specific opinion on the matter it should respond with an empty hash. If the callback chooses to deny the action, it should provide a reason in the response hash. This is a human readable string that may be presented to a user.

At the time of writing, only Grove actually consults checkpoint callbacks. In the future all pebbles must support this. To support callbacks, a pebble must GET /callbacks/allowed/:method/:uid before performing the action. The allowed key in the response will be either true, false or default. true means 'categorically allowed, override default behavior', false means 'categorically' denied, while default means 'apply internal rules, the callbacks had nothing to say about this'. Typically this means no callback was defined for the path in question. If the action has been denied, the response will also include the url of the denying callback along with a textual reason for the denial.

Tagging

Identities support arbitrary sets of tags. (A tag can be any string, including spaces.) The main use case is to allow apps to tag the origin of identities when there may be multiple applications sharing the same realm.

For example, if you develop apps A and B, and these apps tag their identities accordingly, then it's trivial to determine which identities came from which app. If, say, app B is discontinued or must be moved to a separate realm, it's easy to purge/move the identities if they have been tagged correctly.

Tagging is entirely-freeform and can serve any purpose, however.

Custom strategy and provider

A customized installation of Checkpoint might need to implement its own provider and strategy for authentication against an existing user/password store. Refer to config/strategies-example.rb and the checkpoint-strategy gem to set up a Checkpoint compliant provider and strategy.

Known weaknesses

The service defines a critical single point of failure. Infrastructure should be put in place for a redundant solution – either a high-availability memcached cluster or a different key-value store.

Make it so the given identity is banned from the provided path. Will replace any more specific
bans shadowed by this ban. Will not do anything if a more general, equivalent ban is allready in place.
Returns a list of the bans that are actually in effect to comply with this directive.

Delete any effective bans that preclude the given identity from accessing the given path. May delete
a more general ban if required. Returns all bans that were removed.

Checkpoint

Checkpoint is a centralized authentication broker for web applications that supports a number of authentication mechanisms via an http interface. Checkpoint can take care of logging your users into your application and keep track of session and access privileges across services.

Concepts

Realm - The security context for your application. A given session is valid for a specific realm. Realms may span any number of services, but they should ideally be construed as a single coherent 'brand' in the mind of your users. An example realm could be "google" where all the services provided within the 'google' realm shared identities across services.

Domain - A realm is connected to a number of domains (e.g. 'google' realm could be attached to the domains 'maps.google.com' and 'reader.google.com' and even 'youtube.com'). Checkpoint looks at the current host domain to determine the current realm when e.g. logging a user in.

Identity - Represents one specific person. An identity may have a number of accounts.

Account - A verified account with a specific provider that can be used to log in to a specific identity.

Basic config

Checkpoint is provided as an http service and needs to be mapped into the url-space of your application using some proxy mechanism. The standard root url for checkpoint is:

/api/checkpoint/v1/

In production this mapping is done with ha-proxy. In development a rack proxy will be provided.

Typical usage

Given that your basic config is set up, your user can log in by being sent to the appropriate login action. A "Log in with Twitter" link should direct the browser to the following url:

/api/checkpoint/v1/login/twitter

An authentication process will commence possibly taking your user via twitter to confirm their identity. If login is successful your user is returned to your application at:

/login/succeeded

The session key for the logged in user is now stored in the cookie named 'checkpoint.session'. This is a 512 bit hash that can be used with all Pebble-compliant web-services to identify your current user and her credentials. (Unsuccessful logins are returned to: /login/failed)

Currently Checkpoint supports the following authentication mechanisms:

Twitter

Facebook

Google

Origo

Sessions

The basic purpose of Checkpoint is providing and managing sessions for your users. A session in Checkpoint is represented by a 512 bit string of random garbage, the 'session string'. This string can be passed around to all pebbles compliant web services as proof of identity.

To check the identity for a specific session, this call to checkpoint could be used:

Pebbles expect to find the session string in one of two places. First it looks for a url-parameter named 'session', if it is not found there it will attempt to retrieve it from a cookie named 'checkpoint.session'. If neither of these are present the request will be processed without authentication.

Fingerprinting

For each account registered with an identity, one or more fingerprints are recorded for posterity based on the account information. The fingerprint is an SHA-256 hash computed from the immutable parts of the account information, such as one's Twitter UID, mobile number or similar.

The fingerprint obscures the original details but still permits the application to determine if a future credential has been fingerprinted, thus making it possible to ban Twitter users, mobile numbers, etc. without having the original information at hand.

Checkpoint exposes an API that can be used to check for banned fingerprints. This API uses the Pebblebed path system, so that the banning system can be used not only for blocking logins, but for fine-grained access control such as blocking users from posting in a forum.

Callbacks

Pebbles have default rules guarding who gets to do what to a given object. Callbacks allow implementation of custom policies for creating, updating and deleting objects.

A callback is registered with a path and an url. If a callback is registered with the path 'a.b.c' it will be consulted for any action within that path, i.e. it will be called when someone wants to update post:a.b.c.d.e.f.g$11 or post:a.b.c$1, but not post:a$1or post:z.y.x$666.

When a pebble consults checkpoint to determine if an action should be allowed, the callback will post to the url. The post will recieve the parameters method, uid and identity. method will be either 'create', 'update' or 'delete', uid is the uid of the object the action will be taken on, identity is the id of the identity attempting to perform the action. The callback should return a json-hash with the key allowed. If the action should be allowed, allowed should be true, if it should be denied: false. If the callback does not have a specific opinion on the matter it should respond with an empty hash. If the callback chooses to deny the action, it should provide a reason in the response hash. This is a human readable string that may be presented to a user.

At the time of writing, only Grove actually consults checkpoint callbacks. In the future all pebbles must support this. To support callbacks, a pebble must GET /callbacks/allowed/:method/:uid before performing the action. The allowed key in the response will be either true, false or default. true means 'categorically allowed, override default behavior', false means 'categorically' denied, while default means 'apply internal rules, the callbacks had nothing to say about this'. Typically this means no callback was defined for the path in question. If the action has been denied, the response will also include the url of the denying callback along with a textual reason for the denial.

Tagging

Identities support arbitrary sets of tags. (A tag can be any string, including spaces.) The main use case is to allow apps to tag the origin of identities when there may be multiple applications sharing the same realm.

For example, if you develop apps A and B, and these apps tag their identities accordingly, then it's trivial to determine which identities came from which app. If, say, app B is discontinued or must be moved to a separate realm, it's easy to purge/move the identities if they have been tagged correctly.

Tagging is entirely-freeform and can serve any purpose, however.

Custom strategy and provider

A customized installation of Checkpoint might need to implement its own provider and strategy for authentication against an existing user/password store. Refer to config/strategies-example.rb and the checkpoint-strategy gem to set up a Checkpoint compliant provider and strategy.

Known weaknesses

The service defines a critical single point of failure. Infrastructure should be put in place for a redundant solution – either a high-availability memcached cluster or a different key-value store.

Checkpoint

Checkpoint is a centralized authentication broker for web applications that supports a number of authentication mechanisms via an http interface. Checkpoint can take care of logging your users into your application and keep track of session and access privileges across services.

Concepts

Realm - The security context for your application. A given session is valid for a specific realm. Realms may span any number of services, but they should ideally be construed as a single coherent 'brand' in the mind of your users. An example realm could be "google" where all the services provided within the 'google' realm shared identities across services.

Domain - A realm is connected to a number of domains (e.g. 'google' realm could be attached to the domains 'maps.google.com' and 'reader.google.com' and even 'youtube.com'). Checkpoint looks at the current host domain to determine the current realm when e.g. logging a user in.

Identity - Represents one specific person. An identity may have a number of accounts.

Account - A verified account with a specific provider that can be used to log in to a specific identity.

Basic config

Checkpoint is provided as an http service and needs to be mapped into the url-space of your application using some proxy mechanism. The standard root url for checkpoint is:

/api/checkpoint/v1/

In production this mapping is done with ha-proxy. In development a rack proxy will be provided.

Typical usage

Given that your basic config is set up, your user can log in by being sent to the appropriate login action. A "Log in with Twitter" link should direct the browser to the following url:

/api/checkpoint/v1/login/twitter

An authentication process will commence possibly taking your user via twitter to confirm their identity. If login is successful your user is returned to your application at:

/login/succeeded

The session key for the logged in user is now stored in the cookie named 'checkpoint.session'. This is a 512 bit hash that can be used with all Pebble-compliant web-services to identify your current user and her credentials. (Unsuccessful logins are returned to: /login/failed)

Currently Checkpoint supports the following authentication mechanisms:

Twitter

Facebook

Google

Origo

Sessions

The basic purpose of Checkpoint is providing and managing sessions for your users. A session in Checkpoint is represented by a 512 bit string of random garbage, the 'session string'. This string can be passed around to all pebbles compliant web services as proof of identity.

To check the identity for a specific session, this call to checkpoint could be used:

Pebbles expect to find the session string in one of two places. First it looks for a url-parameter named 'session', if it is not found there it will attempt to retrieve it from a cookie named 'checkpoint.session'. If neither of these are present the request will be processed without authentication.

Fingerprinting

For each account registered with an identity, one or more fingerprints are recorded for posterity based on the account information. The fingerprint is an SHA-256 hash computed from the immutable parts of the account information, such as one's Twitter UID, mobile number or similar.

The fingerprint obscures the original details but still permits the application to determine if a future credential has been fingerprinted, thus making it possible to ban Twitter users, mobile numbers, etc. without having the original information at hand.

Checkpoint exposes an API that can be used to check for banned fingerprints. This API uses the Pebblebed path system, so that the banning system can be used not only for blocking logins, but for fine-grained access control such as blocking users from posting in a forum.

Callbacks

Pebbles have default rules guarding who gets to do what to a given object. Callbacks allow implementation of custom policies for creating, updating and deleting objects.

A callback is registered with a path and an url. If a callback is registered with the path 'a.b.c' it will be consulted for any action within that path, i.e. it will be called when someone wants to update post:a.b.c.d.e.f.g$11 or post:a.b.c$1, but not post:a$1or post:z.y.x$666.

When a pebble consults checkpoint to determine if an action should be allowed, the callback will post to the url. The post will recieve the parameters method, uid and identity. method will be either 'create', 'update' or 'delete', uid is the uid of the object the action will be taken on, identity is the id of the identity attempting to perform the action. The callback should return a json-hash with the key allowed. If the action should be allowed, allowed should be true, if it should be denied: false. If the callback does not have a specific opinion on the matter it should respond with an empty hash. If the callback chooses to deny the action, it should provide a reason in the response hash. This is a human readable string that may be presented to a user.

At the time of writing, only Grove actually consults checkpoint callbacks. In the future all pebbles must support this. To support callbacks, a pebble must GET /callbacks/allowed/:method/:uid before performing the action. The allowed key in the response will be either true, false or default. true means 'categorically allowed, override default behavior', false means 'categorically' denied, while default means 'apply internal rules, the callbacks had nothing to say about this'. Typically this means no callback was defined for the path in question. If the action has been denied, the response will also include the url of the denying callback along with a textual reason for the denial.

Tagging

Identities support arbitrary sets of tags. (A tag can be any string, including spaces.) The main use case is to allow apps to tag the origin of identities when there may be multiple applications sharing the same realm.

For example, if you develop apps A and B, and these apps tag their identities accordingly, then it's trivial to determine which identities came from which app. If, say, app B is discontinued or must be moved to a separate realm, it's easy to purge/move the identities if they have been tagged correctly.

Tagging is entirely-freeform and can serve any purpose, however.

Custom strategy and provider

A customized installation of Checkpoint might need to implement its own provider and strategy for authentication against an existing user/password store. Refer to config/strategies-example.rb and the checkpoint-strategy gem to set up a Checkpoint compliant provider and strategy.

Known weaknesses

The service defines a critical single point of failure. Infrastructure should be put in place for a redundant solution – either a high-availability memcached cluster or a different key-value store.

Checkpoint

Checkpoint is a centralized authentication broker for web applications that supports a number of authentication mechanisms via an http interface. Checkpoint can take care of logging your users into your application and keep track of session and access privileges across services.

Concepts

Realm - The security context for your application. A given session is valid for a specific realm. Realms may span any number of services, but they should ideally be construed as a single coherent 'brand' in the mind of your users. An example realm could be "google" where all the services provided within the 'google' realm shared identities across services.

Domain - A realm is connected to a number of domains (e.g. 'google' realm could be attached to the domains 'maps.google.com' and 'reader.google.com' and even 'youtube.com'). Checkpoint looks at the current host domain to determine the current realm when e.g. logging a user in.

Identity - Represents one specific person. An identity may have a number of accounts.

Account - A verified account with a specific provider that can be used to log in to a specific identity.

Basic config

Checkpoint is provided as an http service and needs to be mapped into the url-space of your application using some proxy mechanism. The standard root url for checkpoint is:

/api/checkpoint/v1/

In production this mapping is done with ha-proxy. In development a rack proxy will be provided.

Typical usage

Given that your basic config is set up, your user can log in by being sent to the appropriate login action. A "Log in with Twitter" link should direct the browser to the following url:

/api/checkpoint/v1/login/twitter

An authentication process will commence possibly taking your user via twitter to confirm their identity. If login is successful your user is returned to your application at:

/login/succeeded

The session key for the logged in user is now stored in the cookie named 'checkpoint.session'. This is a 512 bit hash that can be used with all Pebble-compliant web-services to identify your current user and her credentials. (Unsuccessful logins are returned to: /login/failed)

Currently Checkpoint supports the following authentication mechanisms:

Twitter

Facebook

Google

Origo

Sessions

The basic purpose of Checkpoint is providing and managing sessions for your users. A session in Checkpoint is represented by a 512 bit string of random garbage, the 'session string'. This string can be passed around to all pebbles compliant web services as proof of identity.

To check the identity for a specific session, this call to checkpoint could be used:

Pebbles expect to find the session string in one of two places. First it looks for a url-parameter named 'session', if it is not found there it will attempt to retrieve it from a cookie named 'checkpoint.session'. If neither of these are present the request will be processed without authentication.

Fingerprinting

For each account registered with an identity, one or more fingerprints are recorded for posterity based on the account information. The fingerprint is an SHA-256 hash computed from the immutable parts of the account information, such as one's Twitter UID, mobile number or similar.

The fingerprint obscures the original details but still permits the application to determine if a future credential has been fingerprinted, thus making it possible to ban Twitter users, mobile numbers, etc. without having the original information at hand.

Checkpoint exposes an API that can be used to check for banned fingerprints. This API uses the Pebblebed path system, so that the banning system can be used not only for blocking logins, but for fine-grained access control such as blocking users from posting in a forum.

Callbacks

Pebbles have default rules guarding who gets to do what to a given object. Callbacks allow implementation of custom policies for creating, updating and deleting objects.

A callback is registered with a path and an url. If a callback is registered with the path 'a.b.c' it will be consulted for any action within that path, i.e. it will be called when someone wants to update post:a.b.c.d.e.f.g$11 or post:a.b.c$1, but not post:a$1or post:z.y.x$666.

When a pebble consults checkpoint to determine if an action should be allowed, the callback will post to the url. The post will recieve the parameters method, uid and identity. method will be either 'create', 'update' or 'delete', uid is the uid of the object the action will be taken on, identity is the id of the identity attempting to perform the action. The callback should return a json-hash with the key allowed. If the action should be allowed, allowed should be true, if it should be denied: false. If the callback does not have a specific opinion on the matter it should respond with an empty hash. If the callback chooses to deny the action, it should provide a reason in the response hash. This is a human readable string that may be presented to a user.

At the time of writing, only Grove actually consults checkpoint callbacks. In the future all pebbles must support this. To support callbacks, a pebble must GET /callbacks/allowed/:method/:uid before performing the action. The allowed key in the response will be either true, false or default. true means 'categorically allowed, override default behavior', false means 'categorically' denied, while default means 'apply internal rules, the callbacks had nothing to say about this'. Typically this means no callback was defined for the path in question. If the action has been denied, the response will also include the url of the denying callback along with a textual reason for the denial.

Tagging

Identities support arbitrary sets of tags. (A tag can be any string, including spaces.) The main use case is to allow apps to tag the origin of identities when there may be multiple applications sharing the same realm.

For example, if you develop apps A and B, and these apps tag their identities accordingly, then it's trivial to determine which identities came from which app. If, say, app B is discontinued or must be moved to a separate realm, it's easy to purge/move the identities if they have been tagged correctly.

Tagging is entirely-freeform and can serve any purpose, however.

Custom strategy and provider

A customized installation of Checkpoint might need to implement its own provider and strategy for authentication against an existing user/password store. Refer to config/strategies-example.rb and the checkpoint-strategy gem to set up a Checkpoint compliant provider and strategy.

Known weaknesses

The service defines a critical single point of failure. Infrastructure should be put in place for a redundant solution – either a high-availability memcached cluster or a different key-value store.

Checkpoint

Checkpoint is a centralized authentication broker for web applications that supports a number of authentication mechanisms via an http interface. Checkpoint can take care of logging your users into your application and keep track of session and access privileges across services.

Concepts

Realm - The security context for your application. A given session is valid for a specific realm. Realms may span any number of services, but they should ideally be construed as a single coherent 'brand' in the mind of your users. An example realm could be "google" where all the services provided within the 'google' realm shared identities across services.

Domain - A realm is connected to a number of domains (e.g. 'google' realm could be attached to the domains 'maps.google.com' and 'reader.google.com' and even 'youtube.com'). Checkpoint looks at the current host domain to determine the current realm when e.g. logging a user in.

Identity - Represents one specific person. An identity may have a number of accounts.

Account - A verified account with a specific provider that can be used to log in to a specific identity.

Basic config

Checkpoint is provided as an http service and needs to be mapped into the url-space of your application using some proxy mechanism. The standard root url for checkpoint is:

/api/checkpoint/v1/

In production this mapping is done with ha-proxy. In development a rack proxy will be provided.

Typical usage

Given that your basic config is set up, your user can log in by being sent to the appropriate login action. A "Log in with Twitter" link should direct the browser to the following url:

/api/checkpoint/v1/login/twitter

An authentication process will commence possibly taking your user via twitter to confirm their identity. If login is successful your user is returned to your application at:

/login/succeeded

The session key for the logged in user is now stored in the cookie named 'checkpoint.session'. This is a 512 bit hash that can be used with all Pebble-compliant web-services to identify your current user and her credentials. (Unsuccessful logins are returned to: /login/failed)

Currently Checkpoint supports the following authentication mechanisms:

Twitter

Facebook

Google

Origo

Sessions

The basic purpose of Checkpoint is providing and managing sessions for your users. A session in Checkpoint is represented by a 512 bit string of random garbage, the 'session string'. This string can be passed around to all pebbles compliant web services as proof of identity.

To check the identity for a specific session, this call to checkpoint could be used:

Pebbles expect to find the session string in one of two places. First it looks for a url-parameter named 'session', if it is not found there it will attempt to retrieve it from a cookie named 'checkpoint.session'. If neither of these are present the request will be processed without authentication.

Fingerprinting

For each account registered with an identity, one or more fingerprints are recorded for posterity based on the account information. The fingerprint is an SHA-256 hash computed from the immutable parts of the account information, such as one's Twitter UID, mobile number or similar.

The fingerprint obscures the original details but still permits the application to determine if a future credential has been fingerprinted, thus making it possible to ban Twitter users, mobile numbers, etc. without having the original information at hand.

Checkpoint exposes an API that can be used to check for banned fingerprints. This API uses the Pebblebed path system, so that the banning system can be used not only for blocking logins, but for fine-grained access control such as blocking users from posting in a forum.

Callbacks

Pebbles have default rules guarding who gets to do what to a given object. Callbacks allow implementation of custom policies for creating, updating and deleting objects.

A callback is registered with a path and an url. If a callback is registered with the path 'a.b.c' it will be consulted for any action within that path, i.e. it will be called when someone wants to update post:a.b.c.d.e.f.g$11 or post:a.b.c$1, but not post:a$1or post:z.y.x$666.

When a pebble consults checkpoint to determine if an action should be allowed, the callback will post to the url. The post will recieve the parameters method, uid and identity. method will be either 'create', 'update' or 'delete', uid is the uid of the object the action will be taken on, identity is the id of the identity attempting to perform the action. The callback should return a json-hash with the key allowed. If the action should be allowed, allowed should be true, if it should be denied: false. If the callback does not have a specific opinion on the matter it should respond with an empty hash. If the callback chooses to deny the action, it should provide a reason in the response hash. This is a human readable string that may be presented to a user.

At the time of writing, only Grove actually consults checkpoint callbacks. In the future all pebbles must support this. To support callbacks, a pebble must GET /callbacks/allowed/:method/:uid before performing the action. The allowed key in the response will be either true, false or default. true means 'categorically allowed, override default behavior', false means 'categorically' denied, while default means 'apply internal rules, the callbacks had nothing to say about this'. Typically this means no callback was defined for the path in question. If the action has been denied, the response will also include the url of the denying callback along with a textual reason for the denial.

Tagging

Identities support arbitrary sets of tags. (A tag can be any string, including spaces.) The main use case is to allow apps to tag the origin of identities when there may be multiple applications sharing the same realm.

For example, if you develop apps A and B, and these apps tag their identities accordingly, then it's trivial to determine which identities came from which app. If, say, app B is discontinued or must be moved to a separate realm, it's easy to purge/move the identities if they have been tagged correctly.

Tagging is entirely-freeform and can serve any purpose, however.

Custom strategy and provider

A customized installation of Checkpoint might need to implement its own provider and strategy for authentication against an existing user/password store. Refer to config/strategies-example.rb and the checkpoint-strategy gem to set up a Checkpoint compliant provider and strategy.

Known weaknesses

The service defines a critical single point of failure. Infrastructure should be put in place for a redundant solution – either a high-availability memcached cluster or a different key-value store.

Checkpoint

Checkpoint is a centralized authentication broker for web applications that supports a number of authentication mechanisms via an http interface. Checkpoint can take care of logging your users into your application and keep track of session and access privileges across services.

Concepts

Realm - The security context for your application. A given session is valid for a specific realm. Realms may span any number of services, but they should ideally be construed as a single coherent 'brand' in the mind of your users. An example realm could be "google" where all the services provided within the 'google' realm shared identities across services.

Domain - A realm is connected to a number of domains (e.g. 'google' realm could be attached to the domains 'maps.google.com' and 'reader.google.com' and even 'youtube.com'). Checkpoint looks at the current host domain to determine the current realm when e.g. logging a user in.

Identity - Represents one specific person. An identity may have a number of accounts.

Account - A verified account with a specific provider that can be used to log in to a specific identity.

Basic config

Checkpoint is provided as an http service and needs to be mapped into the url-space of your application using some proxy mechanism. The standard root url for checkpoint is:

/api/checkpoint/v1/

In production this mapping is done with ha-proxy. In development a rack proxy will be provided.

Typical usage

Given that your basic config is set up, your user can log in by being sent to the appropriate login action. A "Log in with Twitter" link should direct the browser to the following url:

/api/checkpoint/v1/login/twitter

An authentication process will commence possibly taking your user via twitter to confirm their identity. If login is successful your user is returned to your application at:

/login/succeeded

The session key for the logged in user is now stored in the cookie named 'checkpoint.session'. This is a 512 bit hash that can be used with all Pebble-compliant web-services to identify your current user and her credentials. (Unsuccessful logins are returned to: /login/failed)

Currently Checkpoint supports the following authentication mechanisms:

Twitter

Facebook

Google

Origo

Sessions

The basic purpose of Checkpoint is providing and managing sessions for your users. A session in Checkpoint is represented by a 512 bit string of random garbage, the 'session string'. This string can be passed around to all pebbles compliant web services as proof of identity.

To check the identity for a specific session, this call to checkpoint could be used:

Pebbles expect to find the session string in one of two places. First it looks for a url-parameter named 'session', if it is not found there it will attempt to retrieve it from a cookie named 'checkpoint.session'. If neither of these are present the request will be processed without authentication.

Fingerprinting

For each account registered with an identity, one or more fingerprints are recorded for posterity based on the account information. The fingerprint is an SHA-256 hash computed from the immutable parts of the account information, such as one's Twitter UID, mobile number or similar.

The fingerprint obscures the original details but still permits the application to determine if a future credential has been fingerprinted, thus making it possible to ban Twitter users, mobile numbers, etc. without having the original information at hand.

Checkpoint exposes an API that can be used to check for banned fingerprints. This API uses the Pebblebed path system, so that the banning system can be used not only for blocking logins, but for fine-grained access control such as blocking users from posting in a forum.

Callbacks

Pebbles have default rules guarding who gets to do what to a given object. Callbacks allow implementation of custom policies for creating, updating and deleting objects.

A callback is registered with a path and an url. If a callback is registered with the path 'a.b.c' it will be consulted for any action within that path, i.e. it will be called when someone wants to update post:a.b.c.d.e.f.g$11 or post:a.b.c$1, but not post:a$1or post:z.y.x$666.

When a pebble consults checkpoint to determine if an action should be allowed, the callback will post to the url. The post will recieve the parameters method, uid and identity. method will be either 'create', 'update' or 'delete', uid is the uid of the object the action will be taken on, identity is the id of the identity attempting to perform the action. The callback should return a json-hash with the key allowed. If the action should be allowed, allowed should be true, if it should be denied: false. If the callback does not have a specific opinion on the matter it should respond with an empty hash. If the callback chooses to deny the action, it should provide a reason in the response hash. This is a human readable string that may be presented to a user.

At the time of writing, only Grove actually consults checkpoint callbacks. In the future all pebbles must support this. To support callbacks, a pebble must GET /callbacks/allowed/:method/:uid before performing the action. The allowed key in the response will be either true, false or default. true means 'categorically allowed, override default behavior', false means 'categorically' denied, while default means 'apply internal rules, the callbacks had nothing to say about this'. Typically this means no callback was defined for the path in question. If the action has been denied, the response will also include the url of the denying callback along with a textual reason for the denial.

Tagging

Identities support arbitrary sets of tags. (A tag can be any string, including spaces.) The main use case is to allow apps to tag the origin of identities when there may be multiple applications sharing the same realm.

For example, if you develop apps A and B, and these apps tag their identities accordingly, then it's trivial to determine which identities came from which app. If, say, app B is discontinued or must be moved to a separate realm, it's easy to purge/move the identities if they have been tagged correctly.

Tagging is entirely-freeform and can serve any purpose, however.

Custom strategy and provider

A customized installation of Checkpoint might need to implement its own provider and strategy for authentication against an existing user/password store. Refer to config/strategies-example.rb and the checkpoint-strategy gem to set up a Checkpoint compliant provider and strategy.

Known weaknesses

The service defines a critical single point of failure. Infrastructure should be put in place for a redundant solution – either a high-availability memcached cluster or a different key-value store.

Checkpoint

Checkpoint is a centralized authentication broker for web applications that supports a number of authentication mechanisms via an http interface. Checkpoint can take care of logging your users into your application and keep track of session and access privileges across services.

Concepts

Realm - The security context for your application. A given session is valid for a specific realm. Realms may span any number of services, but they should ideally be construed as a single coherent 'brand' in the mind of your users. An example realm could be "google" where all the services provided within the 'google' realm shared identities across services.

Domain - A realm is connected to a number of domains (e.g. 'google' realm could be attached to the domains 'maps.google.com' and 'reader.google.com' and even 'youtube.com'). Checkpoint looks at the current host domain to determine the current realm when e.g. logging a user in.

Identity - Represents one specific person. An identity may have a number of accounts.

Account - A verified account with a specific provider that can be used to log in to a specific identity.

Basic config

Checkpoint is provided as an http service and needs to be mapped into the url-space of your application using some proxy mechanism. The standard root url for checkpoint is:

/api/checkpoint/v1/

In production this mapping is done with ha-proxy. In development a rack proxy will be provided.

Typical usage

Given that your basic config is set up, your user can log in by being sent to the appropriate login action. A "Log in with Twitter" link should direct the browser to the following url:

/api/checkpoint/v1/login/twitter

An authentication process will commence possibly taking your user via twitter to confirm their identity. If login is successful your user is returned to your application at:

/login/succeeded

The session key for the logged in user is now stored in the cookie named 'checkpoint.session'. This is a 512 bit hash that can be used with all Pebble-compliant web-services to identify your current user and her credentials. (Unsuccessful logins are returned to: /login/failed)

Currently Checkpoint supports the following authentication mechanisms:

Twitter

Facebook

Google

Origo

Sessions

The basic purpose of Checkpoint is providing and managing sessions for your users. A session in Checkpoint is represented by a 512 bit string of random garbage, the 'session string'. This string can be passed around to all pebbles compliant web services as proof of identity.

To check the identity for a specific session, this call to checkpoint could be used:

Pebbles expect to find the session string in one of two places. First it looks for a url-parameter named 'session', if it is not found there it will attempt to retrieve it from a cookie named 'checkpoint.session'. If neither of these are present the request will be processed without authentication.

Fingerprinting

For each account registered with an identity, one or more fingerprints are recorded for posterity based on the account information. The fingerprint is an SHA-256 hash computed from the immutable parts of the account information, such as one's Twitter UID, mobile number or similar.

The fingerprint obscures the original details but still permits the application to determine if a future credential has been fingerprinted, thus making it possible to ban Twitter users, mobile numbers, etc. without having the original information at hand.

Checkpoint exposes an API that can be used to check for banned fingerprints. This API uses the Pebblebed path system, so that the banning system can be used not only for blocking logins, but for fine-grained access control such as blocking users from posting in a forum.

Callbacks

Pebbles have default rules guarding who gets to do what to a given object. Callbacks allow implementation of custom policies for creating, updating and deleting objects.

A callback is registered with a path and an url. If a callback is registered with the path 'a.b.c' it will be consulted for any action within that path, i.e. it will be called when someone wants to update post:a.b.c.d.e.f.g$11 or post:a.b.c$1, but not post:a$1or post:z.y.x$666.

When a pebble consults checkpoint to determine if an action should be allowed, the callback will post to the url. The post will recieve the parameters method, uid and identity. method will be either 'create', 'update' or 'delete', uid is the uid of the object the action will be taken on, identity is the id of the identity attempting to perform the action. The callback should return a json-hash with the key allowed. If the action should be allowed, allowed should be true, if it should be denied: false. If the callback does not have a specific opinion on the matter it should respond with an empty hash. If the callback chooses to deny the action, it should provide a reason in the response hash. This is a human readable string that may be presented to a user.

At the time of writing, only Grove actually consults checkpoint callbacks. In the future all pebbles must support this. To support callbacks, a pebble must GET /callbacks/allowed/:method/:uid before performing the action. The allowed key in the response will be either true, false or default. true means 'categorically allowed, override default behavior', false means 'categorically' denied, while default means 'apply internal rules, the callbacks had nothing to say about this'. Typically this means no callback was defined for the path in question. If the action has been denied, the response will also include the url of the denying callback along with a textual reason for the denial.

Tagging

Identities support arbitrary sets of tags. (A tag can be any string, including spaces.) The main use case is to allow apps to tag the origin of identities when there may be multiple applications sharing the same realm.

For example, if you develop apps A and B, and these apps tag their identities accordingly, then it's trivial to determine which identities came from which app. If, say, app B is discontinued or must be moved to a separate realm, it's easy to purge/move the identities if they have been tagged correctly.

Tagging is entirely-freeform and can serve any purpose, however.

Custom strategy and provider

A customized installation of Checkpoint might need to implement its own provider and strategy for authentication against an existing user/password store. Refer to config/strategies-example.rb and the checkpoint-strategy gem to set up a Checkpoint compliant provider and strategy.

Known weaknesses

The service defines a critical single point of failure. Infrastructure should be put in place for a redundant solution – either a high-availability memcached cluster or a different key-value store.

Redirect safely to any domain within the realm while preserving the session.

Requires that both the origin domain and target domain is attached to the same
realm. This method falls back to a common redirect if the origin and target domain
is the same. To transfer session from 'acme.no' to an url on 'acme-other-place.org' you would
direct the user to an url like this:
'http://acme.no/api/v1/checkpoint/transfer?target_url=http%3A%2F%2Facme-other-place.org'

This is an endpoint for browsers.

Parameter

Type

Description

target_urlRequired

Integer

The full url (including host name) to redirect the user.

Response

Description

301

Redirect.

Grove

Grove is a generic document store layered on top of an actual database such as PostgreSQL. It can store and index structured documents like comments, blog posts, events etc. and organize these documents for easy retrieval later.

Data model

In Grove, a document is any dictionary-type object that can be represented with a JSON hash, including nested hashes. Grove organizes these documents inside posts; a post represents the "posting" of a document. All Grove APIs deal with posts, not documents directly.

A post collects the following information:

UID — a unique ID (see later section on UIDs).

Class — a class which indicates the type of document, typically being application-specific. Grove classes always have the prefix post., eg. post.comment.

Paths — paths that the document is associated with (there must be at least one).

Tags — a list of simple string tags.

Timestamps — timestamps for retrieving documents on a timeline.

Document — the document proper.

Sensitive data — data only available to the identity that has edit access, or to "god" identities.

Document class

The document class is an application-specific period-delimited string of identifiers. This can be used to filter queries, and can be used to distinguish documents of different types from each other.

Examples of typical class names:

post.blog

post.event

post.user_profile

Note that the first identifier must always be post. This signals to other applications that this specific object is handled by Grove.

Paths

Grove's document database can be viewed as a hierarchy of folders. Every document must be associated with at least one path. Paths with wildcards are typically used to query Grove for content.

A path is a period-delimited list of folder names. The first name must be the realm of the document (see Checkpoint for more on realms). The second name is by convention an application identifier, while the rest of the path is application-specific.

Examples of paths:

acmecorp.calendarapp.events.facebook

acmecorp.blogs.postings

acmecorp.blogs.football.postings

acmecorp.users

A document has one canonical path, which is where the "original" document is stored. If you need the document to appear in multiple places in the folder hierarchy you may post it to multiple paths, which will act like "symlinks" to the document, and enable the document to appear in query results as if it were stored in all the provided paths; in reality, the original document is always returned. If the underlying document is updated, it will be updated for all paths.

Folders are created automatically whenever a document is posted; you don't have to manually create them. Any path you postulate is acceptable as long as it is within the realm of your application.

Child objects

It is a convention in Pebble applications to put children of an object in a "subfolder" of its canonical path. A subpath is (conventionally) generated by appending the numeric ID of the parent object to the path and storing the children there.

For example, an article in the football blog:

post.article:acmecorp.blogs.football$323

The numeric ID here is 323. Comments on that article would be inside the path:

post.comment:acmecorp.blogs.football.323

A comment posted to that path would get an UID such as this:

post.comment:acmecorp.blogs.football.323$534

Tags

A set og tags may be applied to any document and subsequently be used to constrain results in queries. A tag is an opaque identifier that may contain letters, digits and underscores (but not spaces).

Occurrences

A document may also be organized on a timeline. A document may have any number of timestamps (occurrences) attached to it. Each timestamp is labeled. This can be used to model start-/end-times for events, or due dates for tasks.

When querying Grove, the result set can be constrained to documents with a specific labeled occurrence and optionally only documents with such an occurrence within a specified time window. This would typically be used to retrieve events that occur on a specific date, or tasks that are overdue.

Synchronization from external sources

When synchronizing data from external sources, you should give the document an external ID (external_id). The external ID may be any string, it may e.g. be the URL or database ID of the source object. The important thing is that it is invariant for the given source object, and that it is unique within the realm of your application. This ensures that updates written by multiple concurrent workers never results in duplicates.

Additionally, Grove supports external documents. If the content of the source document is synchronized to Grove as an external_document (not document) and local edits are written to the document field, Grove ensures that consecutive synchronization operations will not overwrite local edits, while fields that do not have local edits will still be updated from source. An example:

An event is synchronized from facebook to Grove. The fields are written to the external_document, document is blank.

An editor determines that the title of the event is unhelpful ("Big Launch!!!") and creates a local edit writing {"title": "Launch of the new Wagner Niebelung Ring Lego Kits!!!"}

The document now contains the key title while the rest of the content is in external_document.

A client requesting the document will see the merged content of external_document and document.

An updated event is synchronized from facebook. The updated document is written to external_document. The body and title of the source document has been updated from the source.

A client requesting the document sees the updated body, while the title is overridden by the content of document.

Since the external_document is newer than the document and an updated field is overridden the document is now marked as "conflicted" in Grove. An application may provide an interface to the user to resolve this conflict and update the document.

UIDs

Across all pebbles Grove documents are identified by their UIDs. The UID of a Grove document always has base class post. UIDs have the format:

<klass>:<canonical path>$<id>

Typical UIDs will look like this:

post.event:acmecorp.calendarapp.events.facebook$121

post.comment:acmecorp.blogs.fotball.postings.121$453211

Custom permission policies

Grove supports Checkpoint callbacks. You may override Grove's internal rules about who has permissions to create, update and delete what by implementing callbacks.

created_by: Filter by documents created by a Checkpoint identity (specified by UID).

created_after: Filter by documents created after this date (ISO 8601 date).

created_before: Filter by documents created before this date (ISO 8601 date).

unpublished: Either include (accessible unpublished posts will be included with the result) or only (only accessible unpublished posts will be included with the result). The default is to only include published documents.

deleted: If include, accessible deleted posts will be included with the result. The default is to exclude deleted documents.

occurrence[label]: Require that the post have an occurrence with the label specified in this parameter.

occurrence[from]: The occurrences must be later than this timestamp (ISO 8601 timestamp).

occurrence[to]: The occurrences must be earlier than this timestamp (ISO 8601 timestamp).

occurrence[order]: Order either by asc (ascending) or desc (descending).

When creating new posts specify uid without the oid part, (e.g. 'post.event:acme.calendar'),
if you specify the full uid with oid (e.g. 'post.event:acme.calendar$3242') this is considered
an update of the specified document.

If you specify only some of the post attributes they will be replaced without touching
the other attributes. E.g. specify only 'document' to update attributes without touching
occurrences, tags or paths.

Parameter

Type

Description

uidRequired

String

The uid of the post (omitting oid).

postRequired

JSON

The post to create (see readme for details).

post[document]

JSON

The attributes of the post.

post[tags]

JSON

Array of tags for the post.

post[external_id]

JSON

The external_id of the document.

post[paths]

JSON

Array of synonymous paths for the post.

post[occurrences]

JSON

Hash of arrays of timestamps for this post.
E.g. {"start_time" => ['2012-11-14T10:54:22+01:00']}

merge

Boolean

Attributes will be merged on top of post. This allows partial
updates. Conflicts will be retried.

If you specify only some of the post attributes they will be replaced without touching
the other attributes. E.g. specify only 'document' to update attributes without touching
occurrences, tags or paths.

Parameter

Type

Description

postRequired

JSON

The post to create (see readme for details).

uid

String

The uid of the post (omitting oid).

external_id

String

The external_id of the post to update.

post[document]

JSON

The attributes of the post.

post[external_id]

JSON

The external_id of the document.

post[tags]

JSON

Array of tags for the post.

post[paths]

JSON

Array of synonymous paths for the post.

post[occurrences]

JSON

Hash of arrays of timestamps for this post.

merge

Boolean

Attributes will be merged on top of post. This allows partial
updates. Conflicts will be retried.

Query posts retrieving either a specific post or a collection of posts
according to your criteria.

Due to optimizations, only very basic visibility processing is properly supported when
using comma-separated uids in the query. Generally this should only be used for published, not-deleted
posts with unrestricted visibility.

Parameter

Type

Description

uid

String

The uid of a specific post, a comma separated list of uids or a wildcard.
uid query (e.g. "*:acme.invoices.*")

external_id

Integer

The external_id of the post you want.

tags

String

Constrain query by tags. Either a comma separated list of required tags or a
boolean expression like 'paris & !texas' or 'closed & (failed | pending)'.

created_by

Integer

Only documents created by this checkpoint identity will be returned.

created_after

String

Only documents created after this date (yyyy.mm.dd) will be returned.

created_before

String

Only documents created before this date (yyyy.mm.dd) will be returned.

since

String

Only documents created or updated after this timestamp (ISO 8601) will be returned.

unpublished

String

If set to 'include', accessible unpublished posts will be included with the result. If set to 'only', only accessible unpublished posts will be included with the result.

deleted

String

If set to 'include', accessible deleted posts will be included with the result.

occurrence[label]

String

Require that the post have an occurrence with this label.

occurrence[from]

String

The occurrences must be later than this time. Time stamp (ISO 8601).

occurrence[to]

String

The occurrences must be earlier than this time. Time stamp (ISO 8601).

occurrence[order]

String

'asc' or 'desc'. The posts will be ordered by their occurrences in
the specified order.

limit

Integer

The maximum amount of posts to return.

offset

Integer

The index of the first result to return (for pagination).

sort_by

String

Name of field to sort by. Defaults to 'created_at'.

direction

String

Direction of sort. Defaults to 'desc'.

raw

Boolean

If `true`, does not return the merged document, but instead
provides the raw `document`, `external_document` and `occurrences` separately.

editable

string

If `only`, return only posts writable for current_identity. Defaults to `include`.

Only gods or members of an accessgroup may undelete posts. Posts lose their external_id when deleted.
Undeleted posts will have their old external_ids stashed in the document under
the key `external_id`.

Endpoints

Get acks for the current identity. :uids can be a comma delimited list of uids, or a single uid.

GET /acks/:uids

Post feedback for an item:

POST /acks/:uid

:kind is required, and must be a valid label. :value is required and must be an integer. :identity is required and is retrieved from checkpoint using the session key. :external_uid is also required.

Scores

The aggregate scores for each :uid are available through the /scores endpoints.

total_count - how many identities have provided feedback

positive_count - number of ack values that are greater than zero

negative_count - number of ack values that are less than zero

neutral_count - number of ack values that are exactly zero

positive - the sum of positive scores

negative - sum of negative scores

average - average score (total score / total count)

controversiality - a calculation of how much people disagree

histogram - a list of counts per ack value

Endpoints

All scores for an object, grouped by :kind

GET /scores/:uid

All scores of a given kind:

GET /scores/:uid/:kind

Fetch ranked lists. These need to be ranked by an attribute on score. uid includes a wildcard path.

GET /scores/:uid/:kind/rank/:by

Fetch mixes of ranked, randomized scores, segmented by different groups. Go look at the code. Seriously.

GET /scores/:uid/sample

Stats

TODO: implement endpoints at /stats/:path/:more_stuff.

These aggregate data about :scores and :kind (can't aggregate scores of different kinds. Apples and Oranges).

This will deliver stats for paths (i.e. an app, or a region). Currently this is sort of implemented with some hacks, for dittforslag (how many contributors, top contributors, ranked lists of various things -- most controversial, most popular, etc.

This requires support for wildcard paths, which is on the block for the next few days.

Endpoints

Get acks for the current identity. :uids can be a comma delimited list of uids, or a single uid.

GET /acks/:uids

Post feedback for an item:

POST /acks/:uid

:kind is required, and must be a valid label. :value is required and must be an integer. :identity is required and is retrieved from checkpoint using the session key. :external_uid is also required.

Scores

The aggregate scores for each :uid are available through the /scores endpoints.

total_count - how many identities have provided feedback

positive_count - number of ack values that are greater than zero

negative_count - number of ack values that are less than zero

neutral_count - number of ack values that are exactly zero

positive - the sum of positive scores

negative - sum of negative scores

average - average score (total score / total count)

controversiality - a calculation of how much people disagree

histogram - a list of counts per ack value

Endpoints

All scores for an object, grouped by :kind

GET /scores/:uid

All scores of a given kind:

GET /scores/:uid/:kind

Fetch ranked lists. These need to be ranked by an attribute on score. uid includes a wildcard path.

GET /scores/:uid/:kind/rank/:by

Fetch mixes of ranked, randomized scores, segmented by different groups. Go look at the code. Seriously.

GET /scores/:uid/sample

Stats

TODO: implement endpoints at /stats/:path/:more_stuff.

These aggregate data about :scores and :kind (can't aggregate scores of different kinds. Apples and Oranges).

This will deliver stats for paths (i.e. an app, or a region). Currently this is sort of implemented with some hacks, for dittforslag (how many contributors, top contributors, ranked lists of various things -- most controversial, most popular, etc.

This requires support for wildcard paths, which is on the block for the next few days.

Endpoints

Get acks for the current identity. :uids can be a comma delimited list of uids, or a single uid.

GET /acks/:uids

Post feedback for an item:

POST /acks/:uid

:kind is required, and must be a valid label. :value is required and must be an integer. :identity is required and is retrieved from checkpoint using the session key. :external_uid is also required.

Scores

The aggregate scores for each :uid are available through the /scores endpoints.

total_count - how many identities have provided feedback

positive_count - number of ack values that are greater than zero

negative_count - number of ack values that are less than zero

neutral_count - number of ack values that are exactly zero

positive - the sum of positive scores

negative - sum of negative scores

average - average score (total score / total count)

controversiality - a calculation of how much people disagree

histogram - a list of counts per ack value

Endpoints

All scores for an object, grouped by :kind

GET /scores/:uid

All scores of a given kind:

GET /scores/:uid/:kind

Fetch ranked lists. These need to be ranked by an attribute on score. uid includes a wildcard path.

GET /scores/:uid/:kind/rank/:by

Fetch mixes of ranked, randomized scores, segmented by different groups. Go look at the code. Seriously.

GET /scores/:uid/sample

Stats

TODO: implement endpoints at /stats/:path/:more_stuff.

These aggregate data about :scores and :kind (can't aggregate scores of different kinds. Apples and Oranges).

This will deliver stats for paths (i.e. an app, or a region). Currently this is sort of implemented with some hacks, for dittforslag (how many contributors, top contributors, ranked lists of various things -- most controversial, most popular, etc.

This requires support for wildcard paths, which is on the block for the next few days.

Api

The :uid is in the form of a partial pebbles-uid without the object id. In other words, something like this:

`image:myclient.myapp.kittens`

myclient.myapp.kittens is used to scope the image by client, service, user or other criteria. It is a '.'-separated
string of labels.

If the operation succeeds a complete uid is returned with a generated object id, like this:

`image:myclient.myapp.kittens$20120105134610-1498-bp5o`

If the image format is not supported, the action fails with 400 and the content {"error":"format-not-supported"},
if processing times out it fails with the content {"error":"timeout"}.

This action will write progress updates to a streamed HTTP response while submitting to tootsie/uploading image to S3.
Clients may listen for changes to the response in order to provide progress feedback to the user.

If you require processing notifications from tootsie, specify the query-parameter notification_url.
The format of these messages is documented in Tootsie's README

NOTE: the sizes hash for an image after a successfull post request does not indicate whether the image is ready
to be displayed or not (that is, processed by tootsie and available at the S3 URL).

The client can verify that the image is present by trying to fetch the url, and checking if that request fails or not.

This is best implemented in javascript using an image object of which we listen for load or error events.
Example implementation with jQuery:

varpoll=function(url){varretries=0;varloader=newImage();varattempt=function(){jQuery(loader).one('load',function(){// image is ready});jQuery(loader).one('error',function(){// image is not ready continue pollingsetTimeout(attempt,1000);});loader.src=url+"?retry="+retries++;// Need a different url every time, cause Opera will cache it even if it fails};attempt();};

Known issues/TODO

Tiramisu provides a TiramisuUploader jQuery plugin available at /api/tiramisu/v1/assets/tiramisu.js.
This is not yet documented and probably deserves its own wiki page.

Deployment

When configuring this service for production mind the following points:

The service writes to a streamed response in order to provide progress reports to the client
and it uses the header X-Accel-Buffering to disable buffering of output with nginx.

Given that this is an upload service the client_max_body_size of nginx or corresponding
parameter of your other servers and proxies must be set accordingly.

Timeout is a matter of concern. The upload action of this service will not let the user
go until the image is safely uploaded to S3 and at least a thumbnail is ready for
display. Thus unicorn and possibly other services in the http-chain must be configured
to allow considerable connection time. Minutes!

Tiramisu employs Tootsie to transcode the images. An instance of the tootsie pebble must be up and running.

A stream of JSON objects that describe the status of the transfer.
When status is 'completed' an additional key, 'metadata' will be present containing full uid, and path to the file.
On error, the response will be JSON containing the error message. The status will always be 200.

A stream of JSON objects that describe the status of the transfer.
When status is 'completed', an additional key, 'metadata' will be present containing data about the transcoded
formats urls of transcoded files.

The endpoint where you wish to receive notification
when the transfer and scaling job has been completed.

force_jpeg

boolean

Will convert all sizes/versions to jpeg. Defaults to true. Set this to false
in order to support gif and png transcoding

force_orientation

string

Will force set an orientation on image

Response

Description

200

A stream of JSON objects that describe the status of the transfer.
When status is 'completed' an additional key, 'metadata' will be present containing the full uid
as well as information about sizes, aspect ratio, and the paths to the stored images.
On error, the response will be JSON containing the error message. The status will always be 200.

A JSON structure that is exactly like the metadata key returned from the upload endpoint, except with an
appended 'ready' key which is true if the transcoding is completed or false if it is in progress.

Snitch

A service to track reports of objectionable content and the corresponding moderator decisions

Getting Started

Return a paginated list of unprocessed reported resources (i.e. for a moderator to review).

You may also input a list of full UIDs, e.g GET /items/a.b.c$1,a.b.c$2,a.b.c$3. For this type of query
pagination will not be possible as it always returns the exact items and in the exact order as the input uid list.
If an item is not found, it will output a null item in the same position as the input.

Parameter

Type

Description

scope

String

The scope of the reports to fetch. Must be any of
"pending" (any reported items that have no registered decision),
"processed" (Items that have been decided upon),
"reported" (all reported items, including items that have recieved a decision),
"fresh" (any fresh content that has not been marked as seen by a moderator).
If not specified. Default scope is "pending".

sort_by

String

Any of "created_at", "updated_at" or "action_at" Defaults to "created_at".

This is used to notify snitch of the existence of a new resource (i.e. for moderating resources as it
is submitted) To let snitch know a moderator has seen an item, post an action of the kind "seen" (any other action
will also mark the item as seen).

The scope of the reports to fetch. Must be any of
"pending" (any reported items that have no registered decision),
"processed" (Items that have been decided upon),
"reported" (all reported items, including items that have recieved a decision),
"fresh" (any fresh content that has not been marked as seen by a moderator).
If not specified. Default scope is "pending".

Actual removal of content is not performed by snitch, but this will remove the item from the
default list returned by GET /items.
Currently the user reporting a decision must be god of the given realm, but this should be considered a
temporary solution until a proper concept of "moderators" is in place. Both the decision and the decider is
registered with the item in question.

Requires moderator access

Parameter

Type

Description

uidRequired

String

A full or a wildcard uid for what to register desicion on.

actionRequired

JSON

action[kind]Required

String

One of "kept", "removed", "seen", "edited", "recommended" or "recommendation_revoked".

action[rationale]

String

Optionally you can provide a "rationale" label to explain the reason for the
action. Example rationales could be "irrelevant", "adhominem", "hatespeech", "legal", etc.

action[message]

String

An additional human readable explanation of the action. This should be directed
at the offender as this message in the future may be provided to the original poster.

Origami

A service to handle data on organizations and the people associated with them.

Dependencies

Checkpoint

Memcached (for checkpoint)

Basic Object Model

Organization

Unit

A business unit or organizational unit. These are organized in a hierarchy (mechanism TBD).

Group

A group within a Unit. Typically a comittee or workgroup.

Associate

A person who is associated with a realm. They could be members or volunteers or employees or students or whatnot. The type of associate is qualified through affiliations, groups, and capacities.

Affiliation

Describes the relationship between an Associate and an Organization. Typically used to model membership or employee status. A given Associate can have any number of Affiliations with an Organization, e.g. both member and employee.

Capacity

A person is associated with a specific unit in the organization via a role. This role is a simple label. Roles do not need to have counterparts in the Role table.

Role

A Role is a fleshed out description of a role in the realm.

Origami API

organization

units

associates

There is currently no checking for uniqueness across the realm. I.e. you can have as many Anne Olsen as you like.

capacities

There is no PUT for capacities. You would have to identify it by :id, because associates may have multiple capacities (both different roles in the same group, and same role in different groups). If you want to update one, then delete the old one and make a new one.

Role

Maintenance

Imports

When you do an import, a batch gets created, and each entry in the import is a batch item.

To protect against multiple simultaneous imports for a source and realm, we use a batch proxy of which there can only be one.

When the import is completed, the batch proxy still exists, so no further imports can be performed.

When the batch is flushed (moved from batch items into the actual organization hierarchy), then the batch proxy is deleted, and another import can be performed.

The id (numeric) or label
(alphanumeric) that uniquely identifies this affiliation.

Response

Description

201

Successfully created.

403

Unauthorized.

Origami

A service to handle data on organizations and the people associated with them.

Dependencies

Checkpoint

Memcached (for checkpoint)

Basic Object Model

Organization

Unit

A business unit or organizational unit. These are organized in a hierarchy (mechanism TBD).

Group

A group within a Unit. Typically a comittee or workgroup.

Associate

A person who is associated with a realm. They could be members or volunteers or employees or students or whatnot. The type of associate is qualified through affiliations, groups, and capacities.

Affiliation

Describes the relationship between an Associate and an Organization. Typically used to model membership or employee status. A given Associate can have any number of Affiliations with an Organization, e.g. both member and employee.

Capacity

A person is associated with a specific unit in the organization via a role. This role is a simple label. Roles do not need to have counterparts in the Role table.

Role

A Role is a fleshed out description of a role in the realm.

Origami API

organization

units

associates

There is currently no checking for uniqueness across the realm. I.e. you can have as many Anne Olsen as you like.

capacities

There is no PUT for capacities. You would have to identify it by :id, because associates may have multiple capacities (both different roles in the same group, and same role in different groups). If you want to update one, then delete the old one and make a new one.

Role

Maintenance

Imports

When you do an import, a batch gets created, and each entry in the import is a batch item.

To protect against multiple simultaneous imports for a source and realm, we use a batch proxy of which there can only be one.

When the import is completed, the batch proxy still exists, so no further imports can be performed.

When the batch is flushed (moved from batch items into the actual organization hierarchy), then the batch proxy is deleted, and another import can be performed.

The id (numeric) or label
(alphanumeric) that uniquely identifies this associate.

Response

Description

201

Successfully created.

403

Unauthorized.

Origami

A service to handle data on organizations and the people associated with them.

Dependencies

Checkpoint

Memcached (for checkpoint)

Basic Object Model

Organization

Unit

A business unit or organizational unit. These are organized in a hierarchy (mechanism TBD).

Group

A group within a Unit. Typically a comittee or workgroup.

Associate

A person who is associated with a realm. They could be members or volunteers or employees or students or whatnot. The type of associate is qualified through affiliations, groups, and capacities.

Affiliation

Describes the relationship between an Associate and an Organization. Typically used to model membership or employee status. A given Associate can have any number of Affiliations with an Organization, e.g. both member and employee.

Capacity

A person is associated with a specific unit in the organization via a role. This role is a simple label. Roles do not need to have counterparts in the Role table.

Role

A Role is a fleshed out description of a role in the realm.

Origami API

organization

units

associates

There is currently no checking for uniqueness across the realm. I.e. you can have as many Anne Olsen as you like.

capacities

There is no PUT for capacities. You would have to identify it by :id, because associates may have multiple capacities (both different roles in the same group, and same role in different groups). If you want to update one, then delete the old one and make a new one.

Role

Maintenance

Imports

When you do an import, a batch gets created, and each entry in the import is a batch item.

To protect against multiple simultaneous imports for a source and realm, we use a batch proxy of which there can only be one.

When the import is completed, the batch proxy still exists, so no further imports can be performed.

When the batch is flushed (moved from batch items into the actual organization hierarchy), then the batch proxy is deleted, and another import can be performed.

Origami

A service to handle data on organizations and the people associated with them.

Dependencies

Checkpoint

Memcached (for checkpoint)

Basic Object Model

Organization

Unit

A business unit or organizational unit. These are organized in a hierarchy (mechanism TBD).

Group

A group within a Unit. Typically a comittee or workgroup.

Associate

A person who is associated with a realm. They could be members or volunteers or employees or students or whatnot. The type of associate is qualified through affiliations, groups, and capacities.

Affiliation

Describes the relationship between an Associate and an Organization. Typically used to model membership or employee status. A given Associate can have any number of Affiliations with an Organization, e.g. both member and employee.

Capacity

A person is associated with a specific unit in the organization via a role. This role is a simple label. Roles do not need to have counterparts in the Role table.

Role

A Role is a fleshed out description of a role in the realm.

Origami API

organization

units

associates

There is currently no checking for uniqueness across the realm. I.e. you can have as many Anne Olsen as you like.

capacities

There is no PUT for capacities. You would have to identify it by :id, because associates may have multiple capacities (both different roles in the same group, and same role in different groups). If you want to update one, then delete the old one and make a new one.

Role

Maintenance

Imports

When you do an import, a batch gets created, and each entry in the import is a batch item.

To protect against multiple simultaneous imports for a source and realm, we use a batch proxy of which there can only be one.

When the import is completed, the batch proxy still exists, so no further imports can be performed.

When the batch is flushed (moved from batch items into the actual organization hierarchy), then the batch proxy is deleted, and another import can be performed.

The id (numeric) or label
(alphanumeric) that uniquely identifies this capacity.

Response

Description

201

Successfully created.

403

Unauthorized.

Origami

A service to handle data on organizations and the people associated with them.

Dependencies

Checkpoint

Memcached (for checkpoint)

Basic Object Model

Organization

Unit

A business unit or organizational unit. These are organized in a hierarchy (mechanism TBD).

Group

A group within a Unit. Typically a comittee or workgroup.

Associate

A person who is associated with a realm. They could be members or volunteers or employees or students or whatnot. The type of associate is qualified through affiliations, groups, and capacities.

Affiliation

Describes the relationship between an Associate and an Organization. Typically used to model membership or employee status. A given Associate can have any number of Affiliations with an Organization, e.g. both member and employee.

Capacity

A person is associated with a specific unit in the organization via a role. This role is a simple label. Roles do not need to have counterparts in the Role table.

Role

A Role is a fleshed out description of a role in the realm.

Origami API

organization

units

associates

There is currently no checking for uniqueness across the realm. I.e. you can have as many Anne Olsen as you like.

capacities

There is no PUT for capacities. You would have to identify it by :id, because associates may have multiple capacities (both different roles in the same group, and same role in different groups). If you want to update one, then delete the old one and make a new one.

Role

Maintenance

Imports

When you do an import, a batch gets created, and each entry in the import is a batch item.

To protect against multiple simultaneous imports for a source and realm, we use a batch proxy of which there can only be one.

When the import is completed, the batch proxy still exists, so no further imports can be performed.

When the batch is flushed (moved from batch items into the actual organization hierarchy), then the batch proxy is deleted, and another import can be performed.

Origami

A service to handle data on organizations and the people associated with them.

Dependencies

Checkpoint

Memcached (for checkpoint)

Basic Object Model

Organization

Unit

A business unit or organizational unit. These are organized in a hierarchy (mechanism TBD).

Group

A group within a Unit. Typically a comittee or workgroup.

Associate

A person who is associated with a realm. They could be members or volunteers or employees or students or whatnot. The type of associate is qualified through affiliations, groups, and capacities.

Affiliation

Describes the relationship between an Associate and an Organization. Typically used to model membership or employee status. A given Associate can have any number of Affiliations with an Organization, e.g. both member and employee.

Capacity

A person is associated with a specific unit in the organization via a role. This role is a simple label. Roles do not need to have counterparts in the Role table.

Role

A Role is a fleshed out description of a role in the realm.

Origami API

organization

units

associates

There is currently no checking for uniqueness across the realm. I.e. you can have as many Anne Olsen as you like.

capacities

There is no PUT for capacities. You would have to identify it by :id, because associates may have multiple capacities (both different roles in the same group, and same role in different groups). If you want to update one, then delete the old one and make a new one.

Role

Maintenance

Imports

When you do an import, a batch gets created, and each entry in the import is a batch item.

To protect against multiple simultaneous imports for a source and realm, we use a batch proxy of which there can only be one.

When the import is completed, the batch proxy still exists, so no further imports can be performed.

When the batch is flushed (moved from batch items into the actual organization hierarchy), then the batch proxy is deleted, and another import can be performed.

Origami

A service to handle data on organizations and the people associated with them.

Dependencies

Checkpoint

Memcached (for checkpoint)

Basic Object Model

Organization

Unit

A business unit or organizational unit. These are organized in a hierarchy (mechanism TBD).

Group

A group within a Unit. Typically a comittee or workgroup.

Associate

A person who is associated with a realm. They could be members or volunteers or employees or students or whatnot. The type of associate is qualified through affiliations, groups, and capacities.

Affiliation

Describes the relationship between an Associate and an Organization. Typically used to model membership or employee status. A given Associate can have any number of Affiliations with an Organization, e.g. both member and employee.

Capacity

A person is associated with a specific unit in the organization via a role. This role is a simple label. Roles do not need to have counterparts in the Role table.

Role

A Role is a fleshed out description of a role in the realm.

Origami API

organization

units

associates

There is currently no checking for uniqueness across the realm. I.e. you can have as many Anne Olsen as you like.

capacities

There is no PUT for capacities. You would have to identify it by :id, because associates may have multiple capacities (both different roles in the same group, and same role in different groups). If you want to update one, then delete the old one and make a new one.

Role

Maintenance

Imports

When you do an import, a batch gets created, and each entry in the import is a batch item.

To protect against multiple simultaneous imports for a source and realm, we use a batch proxy of which there can only be one.

When the import is completed, the batch proxy still exists, so no further imports can be performed.

When the batch is flushed (moved from batch items into the actual organization hierarchy), then the batch proxy is deleted, and another import can be performed.

A type-neutral delete. Provide any valid uid-query for any kind of Origami
resource. E.g. list a number of objects of varying types and have them
all deleted together here.

Parameter

Type

Description

realmRequired

String

The Checkpoint security realm.

uidRequired

String

The pebbles uid, a comma separated list of uids. Wildcard uids are rejected for safety.

Response

Description

200

JSON

403

Unauthorized.

Origami

A service to handle data on organizations and the people associated with them.

Dependencies

Checkpoint

Memcached (for checkpoint)

Basic Object Model

Organization

Unit

A business unit or organizational unit. These are organized in a hierarchy (mechanism TBD).

Group

A group within a Unit. Typically a comittee or workgroup.

Associate

A person who is associated with a realm. They could be members or volunteers or employees or students or whatnot. The type of associate is qualified through affiliations, groups, and capacities.

Affiliation

Describes the relationship between an Associate and an Organization. Typically used to model membership or employee status. A given Associate can have any number of Affiliations with an Organization, e.g. both member and employee.

Capacity

A person is associated with a specific unit in the organization via a role. This role is a simple label. Roles do not need to have counterparts in the Role table.

Role

A Role is a fleshed out description of a role in the realm.

Origami API

organization

units

associates

There is currently no checking for uniqueness across the realm. I.e. you can have as many Anne Olsen as you like.

capacities

There is no PUT for capacities. You would have to identify it by :id, because associates may have multiple capacities (both different roles in the same group, and same role in different groups). If you want to update one, then delete the old one and make a new one.

Role

Maintenance

Imports

When you do an import, a batch gets created, and each entry in the import is a batch item.

To protect against multiple simultaneous imports for a source and realm, we use a batch proxy of which there can only be one.

When the import is completed, the batch proxy still exists, so no further imports can be performed.

When the batch is flushed (moved from batch items into the actual organization hierarchy), then the batch proxy is deleted, and another import can be performed.

The id (numeric) or label
(alphanumeric) that uniquely identifies this role.

Response

Description

201

Successfully created.

403

Unauthorized.

Origami

A service to handle data on organizations and the people associated with them.

Dependencies

Checkpoint

Memcached (for checkpoint)

Basic Object Model

Organization

Unit

A business unit or organizational unit. These are organized in a hierarchy (mechanism TBD).

Group

A group within a Unit. Typically a comittee or workgroup.

Associate

A person who is associated with a realm. They could be members or volunteers or employees or students or whatnot. The type of associate is qualified through affiliations, groups, and capacities.

Affiliation

Describes the relationship between an Associate and an Organization. Typically used to model membership or employee status. A given Associate can have any number of Affiliations with an Organization, e.g. both member and employee.

Capacity

A person is associated with a specific unit in the organization via a role. This role is a simple label. Roles do not need to have counterparts in the Role table.

Role

A Role is a fleshed out description of a role in the realm.

Origami API

organization

units

associates

There is currently no checking for uniqueness across the realm. I.e. you can have as many Anne Olsen as you like.

capacities

There is no PUT for capacities. You would have to identify it by :id, because associates may have multiple capacities (both different roles in the same group, and same role in different groups). If you want to update one, then delete the old one and make a new one.

Role

Maintenance

Imports

When you do an import, a batch gets created, and each entry in the import is a batch item.

To protect against multiple simultaneous imports for a source and realm, we use a batch proxy of which there can only be one.

When the import is completed, the batch proxy still exists, so no further imports can be performed.

When the batch is flushed (moved from batch items into the actual organization hierarchy), then the batch proxy is deleted, and another import can be performed.