# fyi.opensocial.provisionGroup

> Published by [lexicons.opensocial.fyi](https://lexicon.garden/identity/did:plc:2gqnilpksz2e7faj3bwvo6qc)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:2gqnilpksz2e7faj3bwvo6qc/fyi.opensocial.provisionGroup)
- [Documentation](https://lexicon.garden/lexicon/did:plc:2gqnilpksz2e7faj3bwvo6qc/fyi.opensocial.provisionGroup/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:2gqnilpksz2e7faj3bwvo6qc/fyi.opensocial.provisionGroup/examples)

## Definitions

### `fyi.opensocial.provisionGroup`

**Type**: `procedure`

Host-level: an app creates a group for a person and gets its own OAuth session on it. Authenticated twice: the person asking, by service auth from their PDS (they become the founder), and the app, by OAuth client authentication in the body (a client assertion for a confidential client) with a DPoP proof in the `DPoP` header, exactly as at the token endpoint. The app must be one this host provisions for. Returns the group and a token response bound to the proof's key, issued to the app's client id: refreshed, listed and revoked like any other session on the group.

#### Input

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `client_assertion` | `string` | No |  |
| `client_assertion_type` | `string` | No |  |
| `client_id` | `string` | Yes |  |
| `description` | `string` | No |  |
| `displayName` | `string` | Yes |  |
| `handle` | `string` (handle) | Yes |  |
| `joinPolicy` | `string` | No |  |
| `metaReadableBy` | `array` | No |  |
| `scope` | `string` | Yes | The OAuth scope the app wants on the group. Must include `atproto`, and every entry must be one the app's client metadata declares. |
| `stewards` | `array` | No | Accounts that run the group alongside the founder. |

#### Output

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `did` | `string` (did) | Yes |  |
| `members` | `string` (space-ref) | Yes |  |
| `meta` | `string` (space-ref) | Yes |  |
| `session` | `unknown` | Yes | An OAuth token response (access_token, token_type, refresh_token, expires_in, scope, sub), as /oauth/token returns it. |

#### Errors

- **UntrustedApp**
- **InvalidScope**
- **use_dpop_nonce**
- **HandleTaken**

## Raw Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "main": {
      "description": "Host-level: an app creates a group for a person and gets its own OAuth session on it. Authenticated twice: the person asking, by service auth from their PDS (they become the founder), and the app, by OAuth client authentication in the body (a client assertion for a confidential client) with a DPoP proof in the `DPoP` header, exactly as at the token endpoint. The app must be one this host provisions for. Returns the group and a token response bound to the proof's key, issued to the app's client id: refreshed, listed and revoked like any other session on the group.",
      "errors": [
        {
          "name": "UntrustedApp"
        },
        {
          "name": "InvalidScope"
        },
        {
          "name": "use_dpop_nonce"
        },
        {
          "name": "HandleTaken"
        }
      ],
      "input": {
        "encoding": "application/json",
        "schema": {
          "properties": {
            "client_assertion": {
              "type": "string"
            },
            "client_assertion_type": {
              "type": "string"
            },
            "client_id": {
              "type": "string"
            },
            "description": {
              "maxGraphemes": 300,
              "maxLength": 3000,
              "type": "string"
            },
            "displayName": {
              "maxGraphemes": 64,
              "maxLength": 640,
              "type": "string"
            },
            "handle": {
              "format": "handle",
              "type": "string"
            },
            "joinPolicy": {
              "type": "string"
            },
            "metaReadableBy": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "scope": {
              "description": "The OAuth scope the app wants on the group. Must include `atproto`, and every entry must be one the app's client metadata declares.",
              "type": "string"
            },
            "stewards": {
              "description": "Accounts that run the group alongside the founder.",
              "items": {
                "format": "did",
                "type": "string"
              },
              "type": "array"
            }
          },
          "required": [
            "handle",
            "displayName",
            "scope",
            "client_id"
          ],
          "type": "object"
        }
      },
      "output": {
        "encoding": "application/json",
        "schema": {
          "properties": {
            "did": {
              "format": "did",
              "type": "string"
            },
            "members": {
              "format": "space-ref",
              "type": "string"
            },
            "meta": {
              "format": "space-ref",
              "type": "string"
            },
            "session": {
              "description": "An OAuth token response (access_token, token_type, refresh_token, expires_in, scope, sub), as /oauth/token returns it.",
              "type": "unknown"
            }
          },
          "required": [
            "did",
            "meta",
            "members",
            "session"
          ],
          "type": "object"
        }
      },
      "type": "procedure"
    }
  },
  "id": "fyi.opensocial.provisionGroup",
  "lexicon": 1
}
```