Registering a Client

To use the GNU MediaGoblin API you need to use the dynamic client registration. This has been adapted from the OpenID specification, 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.

The endpoint is /api/client/register

The parameters are:

type

required - This must be either client_associate (for new registration) or client_update

client_id

update only - This should only be used updating client information, this is the client_id given when you register

client_secret

update only - This should only be used updating client information, this is the client_secret given when you register

contacts

optional - This a space seporated list of email addresses to contact of people responsible for the client

application_type

required - This is the type of client you are making, this must be either web or native

application_name

optional - This is the name of your client

logo_url

optional - This is a URL of the logo image for your client

redirect_uri

optional - This is a space seporated list of pre-registered URLs for use at the Authorization Server

Response

You will get back a response:

client_id

This identifies a client

client_secret

This is the secret.

expires_at

This is time that the client credentials expire. If this is 0 the client registration does not expire.

Example

Register Client

To register a client for the first time, this is the minimum you must supply:

{
    "type": "client_associate",
    "application_type": "native"
}

A Response will look like:

{
    "client_secret": "hJtfhaQzgKerlLVdaeRAgmbcstSOBLRfgOinMxBCHcb",
    "expires_at": 0,
    "client_id": "vwljdhUMhhNbdKizpjZlxv"
}

Updating Client

Using the response we got above we can update the information and add new information we may have opted not to supply:

{
    "type": "client_update",
    "client_id": "vwljdhUMhhNbdKizpjZlxv",
    "client_secret": "hJtfhaQzgKerlLVdaeRAgmbcstSOBLRfgOinMxBCHcb",
    "application_type": "web",
    "application_name": "MyClient!",
    "logo_url": "https://myclient.org/images/my_logo.png",
    "contacts": "myemail@someprovider.com another_developer@provider.net",
}

The response will just return back the client_id and client_secret you sent:

{
    "client_id": "vwljdhUMhhNbdKizpjZlxv",
    "client_secret": "hJtfhaQzgKerlLVdaeRAgmbcstSOBLRfgOinMxBCHcb",
    "expires_at": 0
}

Errors

There are a number of errors you could get back, This explains what could cause some of them:

Could not decode data

This is caused when you have an error in the encoding of your data.

Unknown Content-Type

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.

No registration type provided

This is when you leave out the type. This should either be client_update or client_associate

Unknown application_type.

This is when you have provided a type however this isn’t one of the known types.

client_id is required to update.

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.

client_secret is required to update.

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.

Unauthorized.

This is when you are trying to update however the client_id and/or client_secret you have submitted are incorrect.

Only set client_id for update.

This should only be given when you update.

Only set client_secret for update.

This should only be given when you update.

Logo URL <url> is not a valid URL

This is when the URL specified did not meet the validation.

contacts must be a string of space-separated email addresses.

contacts should be a string (not a list), ensure each email is seporated by a space

Email <email> is not a valid email

This is when you have submitted an invalid email address

redirect_uris must be space-separated URLs.

redirect_uris should be a string (not a list), ensure each URL is seporated by a space

URI <URI> is not a valid URI

This is when your URI is invalid.