docs/source/api/client_register.rst

   1 .. MediaGoblin Documentation
   2
   3    Written in 2011, 2012 by MediaGoblin contributors
   4
   5    To the extent possible under law, the author(s) have dedicated all
   6    copyright and related and neighboring rights to this software to
   7    the public domain worldwide. This software is distributed without
   8    any warranty.
   9
  10    You should have received a copy of the CC0 Public Domain
  11    Dedication along with this software. If not, see
  12    <http://creativecommons.org/publicdomain/zero/1.0/>.
  13
  14 ====================
  15 Registering a Client
  16 ====================
  17
  18 To use the GNU MediaGoblin API you need to use the dynamic client registration. This has been adapted from the `OpenID specification <https://openid.net/specs/openid-connect-registration-1_0.html>`_, this is the only part of OpenID that is being used to serve the purpose to provide the client registration which is used in OAuth.
  19
  20 The endpoint is ``/api/client/register``
  21
  22 The parameters are:
  23
  24 type
  25     **required** - This must be either *client_associate* (for new registration) or *client_update*
  26
  27 client_id
  28     **update only** - This should only be used updating client information, this is the client_id given when you register
  29
  30 client_secret
  31     **update only** - This should only be used updating client information, this is the client_secret given when you register
  32
  33 contacts
  34     **optional** - This a space seporated list of email addresses to contact of people responsible for the client
  35
  36 application_type
  37     **required** - This is the type of client you are making, this must be either *web* or *native*
  38
  39 application_name
  40     **optional** - This is the name of your client
  41
  42 logo_uri
  43     **optional** - This is a URI of the logo image for your client
  44
  45 redirect_uri
  46     **optional** - This is a space seporated list of pre-registered URLs for use at the Authorization Server
  47
  48
  49 Response
  50 --------
  51
  52 You will get back a response:
  53
  54 client_id
  55     This identifies a client
  56
  57 client_secret
  58     This is the secret.
  59
  60 expires_at
  61     This is time that the client credentials expire. If this is 0 the client registration does not expire.
  62
  63 =======
  64 Example
  65 =======
  66
  67 Register Client
  68 ---------------
  69
  70 To register a client for the first time, this is the minimum you must supply::
  71
  72     {
  73         "type": "client_associate",
  74         "application_type": "native"
  75     }
  76
  77 A Response will look like::
  78
  79     {
  80         "client_secret": "hJtfhaQzgKerlLVdaeRAgmbcstSOBLRfgOinMxBCHcb",
  81         "expires_at": 0,
  82         "client_id": "vwljdhUMhhNbdKizpjZlxv"
  83     }
  84
  85
  86 Updating Client
  87 ---------------
  88
  89 Using the response we got above we can update the information and add new information we may have opted not to supply::
  90
  91     {
  92         "type": "client_update",
  93         "client_id": "vwljdhUMhhNbdKizpjZlxv",
  94         "client_secret": "hJtfhaQzgKerlLVdaeRAgmbcstSOBLRfgOinMxBCHcb",
  95         "application_type": "web",
  96         "application_name": "MyClient!",
  97         "logo_uri": "https://myclient.org/images/my_logo.png",
  98         "contacts": "myemail@someprovider.com another_developer@provider.net",
  99     }
 100
 101 The response will just return back the client_id and client_secret you sent::
 102
 103     {
 104         "client_id": "vwljdhUMhhNbdKizpjZlxv",
 105         "client_secret": "hJtfhaQzgKerlLVdaeRAgmbcstSOBLRfgOinMxBCHcb",
 106         "expires_at": 0
 107     }
 108
 109
 110 ======
 111 Errors
 112 ======
 113
 114 There are a number of errors you could get back, This explains what could cause some of them:
 115
 116 Could not decode data
 117     This is caused when you have an error in the encoding of your data.
 118
 119 Unknown Content-Type
 120     You should sent a Content-Type header with when you make a request, this should be either application/json or www-form-urlencoded. This is caused when a unknown Content-Type is used.
 121
 122 No registration type provided
 123     This is when you leave out the ``type``. This should either be client_update or client_associate
 124
 125 Unknown application_type.
 126     This is when you have provided a ``type`` however this isn't one of the known types.
 127
 128 client_id is required to update.
 129     When you try and update you need to specify the client_id, this will be what you were given when you initially registered the client.
 130
 131 client_secret is required to update.
 132     When you try to update you need to specify the client_secrer, this will be what you were given when you initially register the client.
 133
 134 Unauthorized.
 135     This is when you are trying to update however the client_id and/or client_secret you have submitted are incorrect.
 136
 137 Only set client_id for update.
 138     This should only be given when you update.
 139
 140 Only set client_secret for update.
 141     This should only be given when you update.
 142
 143 Logo URL <url> is not a valid URL
 144     This is when the URL specified did not meet the validation.
 145
 146 contacts must be a string of space-separated email addresses.
 147     ``contacts`` should be a string (not a list), ensure each email is seporated by a space
 148
 149 Email <email> is not a valid email
 150     This is when you have submitted an invalid email address
 151
 152 redirect_uris must be space-separated URLs.
 153     ``redirect_uris`` should be a string (not a list), ensure each URL is seporated by a space
 154
 155 URI <URI> is not a valid URI
 156     This is when your URI is invalid.
 157