# app/Http/Controllers/Organisation/*

This documentation serves to explain the purpose, usage, bugs and future direction of the code used for the organisation controllers.

# Internal API Controller ( AdminApiController.php )
This serves as the entrypoint for API usage within both GSL and it's sister brands and partners to make changes to the state of Creatia's understanding of what organisations and users have access to what, whether they have access at all, and so forth. It currently allows the association of an external identifiers with organisations on the creation of an organisation, the creation of users for a given organisation, and the retrieval of a list of external identifiers.

## get_external_identities(request)
- **request** (_Laravel Request_): The Laravel request object containing relevant fields. Fields:
    - **application** (_String of any form_): This is used to identify the type of identity we're looking at. An example of this might be gsl-whmcs, gd-whmcs, sl-whmcs, this does not much matter as long as it is consistent. It is how your application will be able to go "I want to know my Creatia ID based upon my own application ID I've generated"
    - **identity** (_String, in freeform_): This is the actual identifier you will use


You can use this to retrieve a list of organisations and their respective creatia identifier using a given application, or you can retrieve a specific organisation using an application and idetntiy.

Examples of usage are below:

```
GET https://api-creatia.securelayer.com/api/internal/organisation

QUERY STRUCTURE 1: {
    "application": "gd-whmcs"
}

QUERY STRUCTURE 2: {
    "application": "gd-whmcs",
    "identity": "121"
}
```

## create_organisation(request)
- **request** (_Laravel Request_): The Laravel request object containing relevant fields. Fields:
    - **name** (_String of any form_): This is the name for a given organisation.
    - **subtenant** (_String, either of form gsl, go-dedicated, streamline_): The brand that this organisation should be associated with. If GSL, no association will be formed as it's a freeform organisation. If the other two, the organisation will be a suborganisation of that brand.
    - **identifiers** (Array described by the following - You can have as many identifiers as you'd like.):
        - **key** (_String of any form_): This is used to identify the type of identity we're looking at. An example of this might be gsl-whmcs, gd-whmcs, sl-whmcs, this does not much matter as long as it is consistent. It is how your application will be able to go "I want to know my Creatia ID based upon my own application ID I've generated"
        - **identity** (_String, in freeform_): This is the actual identifier you will use

Examples of usage are below:

```
POST https://api-creatia.securelayer.com/api/internal/organisation

JSON PAYLOAD: {
    "name": "Local Insecure Spaghetti",
    "identifiers": [
        {
            "key": "gd-whmcs",
            "identity": "121"
        }
    ],
    "subtenant": "go-dedicated"
}
```

This would create an organisation called "Local Insecure Spaghetti" with an external identifier marked as gd-whmcs evaluating to 121, so the application with the identifier gd-whmcs could then pass that application / identity combination to determine the Creatia ID in the get_external_identities endpoint.