Users and Organizations

David Moore edited this page Jun 11, 2014 · 29 revisions

User profile is a document type that defines an authenticated user in PMP. Users can access and modify content in PMP, based on their association with various Permission Groups and the permission rights defined on the content itself.

Profile Definition

Canonical version of the User profile definition must be retrieved at: https://api.pmp.io/profiles/user

Canonical version of the Organization profile definition must be retrieved at: https://api.pmp.io/profiles/organization. Organization is a sub-profile of the user profile that slightly extends user and mostly provides more specific scope.

User profile should look something like the following (please do not treat example here as reference, it is probably outdated and/or inaccurate!):

{
  "version": "1.0"
, "attributes": {
    "valid": {
      "from": "2013-02-11T13:21:31+00:00"
    , "to": "3013-05-11T13:21:31+00:00"
    }
  , "created": "2013-10-17T17:24:46+00:00"
  , "modified": "2013-10-22T20:19:43+00:00"
  , "guid": "621a1ab8-a78b-48bf-8fbb-776d3d2a82d1"
  , "title": "User Profile"
  , "published": "2013-02-11T13:21:31+00:00"
  }
, "links": {
    "profile": [
      {
        "href": "https://api-sandbox.pmp.io/profiles/profile"
      }
    ]
  , "documentation": [
      {
        "href": "https://github.com/publicmediaplatform/pmpdocs/wiki/Users-and-Organizations"
      , "type": "text/html"
      }
    ]
  , "schema": [
      {
        "href": "https://api-sandbox.pmp.io/schemas/user"
      , "scope": "update"
      , "type": "application/schema+json"
      }
    ]
  , "alternate": [
      {
        "href": "https://api-sandbox.pmp.io/profiles/user"
      }
    ]
  , "creator": [
      {
        "href": "https://api-sandbox.pmp.io/docs/af676335-21df-4486-ab43-e88c1b48f026"
      }
    ]
  , "navigation": [
      {
        "href": "https://api-sandbox.pmp.io/docs?guid=621a1ab8-a78b-48bf-8fbb-776d3d2a82d1"
      , "rels": [
          "urn:pmp:navigation:self"
        ]
      }
    ]
  , "edit": [ARRAY]
  }
}

Organization profile should look something like the following (please do not treat example here as reference, it is probably outdated and/or inaccurate!):

{
  "version": "1.0"
, "attributes": {
    "valid": {
      "from": "2013-02-11T13:21:31+00:00"
    , "to": "3013-05-11T13:21:31+00:00"
    }
  , "created": "2013-10-17T17:24:46+00:00"
  , "modified": "2013-10-22T20:19:44+00:00"
  , "guid": "3ae037fb-7d8e-4a42-958a-05dd326ef5ed"
  , "title": "Organization Profile"
  , "published": "2013-02-11T13:21:31+00:00"
  }
, "links": {
    "profile": [
      {
        "href": "https://api-sandbox.pmp.io/profiles/profile"
      }
    ]
  , "extends": [
      {
        "href": "https://api-sandbox.pmp.io/profiles/user"
      }
    ]
  , "documentation": [
      {
        "href": "https://github.com/publicmediaplatform/pmpdocs/wiki/Users-and-Organizations"
      , "type": "text/html"
      }
    ]
  , "schema": [
      {
        "href": "https://api-sandbox.pmp.io/schemas/user"
      , "scope": "update"
      , "type": "application/schema+json"
      }
    ]
  , "alternate": [
      {
        "href": "https://api-sandbox.pmp.io/profiles/organization"
      }
    ]
  , "creator": [
      {
        "href": "https://api-sandbox.pmp.io/docs/af676335-21df-4486-ab43-e88c1b48f026"
      }
    ]
  , "navigation": [
      {
        "href": "https://api-sandbox.pmp.io/docs?guid=3ae037fb-7d8e-4a42-958a-05dd326ef5ed"
      , "rels": [
          "urn:pmp:navigation:self"
        ]
      }
    ]
  , "edit": [ARRAY]
  }
}

Sample Document

{
 "version": "1.0"
, "attributes": {
    "auth": {
      "clients": [
        {
          "access_token": "...REDACTED..."
        , "client_id": "...REDACTED..."
        , "client_secret": "...REDACTED..."
        , "label": "iPhone read-only"
        , "scope": "read"
        , "token_expires_in": 360000
        , "token_issue_date": "2013-05-11T13:21:31.598Z"
        }
      , {
          "access_token": "...REDACTED..."
        , "client_id": "...REDACTED..."
        , "client_secret": "...REDACTED..."
        , "label": "CMS read/write"
        , "scope": "write"
        , "token_expires_in": 360000
        , "token_issue_date": "2013-05-10T13:21:31.598Z"
        }
      ]
    , "pass_hash": "...REDACTED..."
    , "user": "npr"
    }
  , "created": "2013-10-01T18:59:31+00:00"
  , "guid": "6140faf0-fb45-4a95-859a-070037fafa01"
  , "modified": "2013-10-22T20:32:28+00:00"
  , "published": "2013-10-01T18:59:31+00:00"
  , "tags": [
      "testcontent"
    ]
  , "title": "NPR Digital Media"
  , "valid": {
      "from": "2013-10-01T18:59:31+00:00"
    , "to": "3013-10-01T18:59:31+00:00"
    }
  }
, "links": {
    "creator": [
      {
        "href": "https://api-sandbox.pmp.io/docs/af676335-21df-4486-ab43-e88c1b48f026"
      }
    ]
  , "edit": []
  , "navigation": [
      {
        "href": "https://api-sandbox.pmp.io/docs?guid=6140faf0-fb45-4a95-859a-070037fafa01"
      , "rels": [
          "urn:pmp:navigation:self"
        ]
      }
    ]
  , "profile": [
      {
        "href": "https://api-sandbox.pmp.io/profiles/user"
      }
    ]
  }
}

PLEASE NOTE that the "auth" attribute is displayed here for demonstration purposes only and to show how the document is saved. "Auth" property is always redacted from API output for security reasons. Clients MUST use Authentication API to access this values, instead of Document API.

Document Semantics

User profile is an extension of Collection.doc+JSON media type. It inherits all of the defined semantics of the media type and adds following field definitions:

  • enclosure - can be used to provide user avatars or organization logos (for: the related organization profile)

  • address - address of the user or an organization

  • emails - this field can hold various types of contact e-mails associated with the account.

  • pingbacks - indicates different mechanisms to "ping-back" publisher once its content item publishing request is fully processed.

  • auth - authentication information compliant with OAuth2 spec. ATTENTION most subfields pf this field are read-only. You cannot modify them when updating a user document. You have to use a separate Auth API instead.

    Displaying: only the "user" sub-field is allowed during display of this content

    Saving: consumers of the API can send "user" and "password" fields. The "password" field will never be actually saved. It will be salted and hashed and saved as: pass_hash field.

    • pass_hash - hash of the password.
    • scope - you can limit the access scope per client. Implemented scopes:
      • read: do not allow any PUT, POST, PATCH or DELETE Api calls. Useful for insecure clients
      • write: give full access that the user would have.