2. Paramètre de Requête "authorization_details"

Le paramètre de requête authorization_details contient, en notation JSON, un tableau d'objets. Chaque objet JSON contient les données pour spécifier les exigences d'autorisation pour un certain type de ressource. Le type de ressource ou d'exigence d'accès est déterminé par le champ type, qui est défini comme suit:

type: Un identifiant pour le type de détails d'autorisation sous forme de chaîne. La valeur du champ type détermine le contenu autorisé de l'objet qui le contient. La valeur est unique pour l'API décrite dans le contexte de l'AS. Ce champ est OBLIGATOIRE (REQUIRED).

Un tableau authorization_details PEUT contenir plusieurs entrées du même type.

La figure 2 montre un authorization_details de type payment_initiation utilisant les données d'exemple ci-dessus:

[
  {
    "type": "payment_initiation",
    "actions": [
      "initiate",
      "status",
      "cancel"
    ],
    "locations": [
      "https://example.com/payments"
    ],
    "instructedAmount": {
      "currency": "EUR",
      "amount": "123.50"
    },
    "creditorName": "Merchant A",
    "creditorAccount": {
      "iban": "DE02100100109307118603"
    },
    "remittanceInformationUnstructured": "Ref Number Merchant"
  }
]

La figure 3 montre une demande combinée demandant l'accès aux informations de compte et la permission d'initier un paiement:

[
  {
    "type": "account_information",
    "actions": [
      "list_accounts",
      "read_balances",
      "read_transactions"
    ],
    "locations": [
      "https://example.com/accounts"
    ]
  },
  {
    "type": "payment_initiation",
    "actions": [
      "initiate",
      "status",
      "cancel"
    ],
    "locations": [
      "https://example.com/payments"
    ],
    "instructedAmount": {
      "currency": "EUR",
      "amount": "123.50"
    },
    "creditorName": "Merchant A",
    "creditorAccount": {
      "iban": "DE02100100109307118603"
    },
    "remittanceInformationUnstructured": "Ref Number Merchant"
  }
]

Les objets JSON avec des champs de type account_information et payment_initiation représentent les différents détails d'autorisation à utiliser par l'AS pour demander le consentement.

Note: L'AS rendra ces données ultérieurement disponibles aux RS respectifs (voir Section 9).

2.1. Types de Détails d'Autorisation (Authorization Details Types)

L'AS contrôle l'interprétation de la valeur du paramètre type ainsi que les champs d'objet que le paramètre type autorise. Cependant, la valeur du paramètre type est également généralement documentée et destinée à être utilisée par les développeurs. Il est RECOMMANDÉ que les concepteurs d'API choisissent des valeurs de type facilement copiables sans ambiguïté. Par exemple, certains glyphes ont plusieurs points de code Unicode pour le même caractère visuel, et un développeur pourrait potentiellement taper un caractère différent de celui défini par l'AS. Les moyens possibles de réduire la confusion potentielle sont de limiter la valeur aux caractères ASCII [RFC0020], de fournir une liste lisible par machine des valeurs de type de données, ou d'instruire les développeurs de copier et coller directement depuis la documentation.

Si une application ou une API est censée être déployée sur différents serveurs, comme dans le cas d'une norme ouverte, il est RECOMMANDÉ au concepteur d'API d'utiliser un espace de noms résistant aux collisions sous son contrôle, tel qu'un URI que le concepteur d'API contrôle.

L'exemple suivant montre comment une implémentation pourrait utiliser l'espace de noms https://scheme.example.org/ pour garantir des valeurs de type résistantes aux collisions:

{
  "type": "https://scheme.example.org/files",
  "locations": [
    "https://example.com/files"
  ],
  "permissions": [
    {
      "path": "/myfiles/A",
      "access": [
        "read"
      ]
    },
    {
      "path": "/myfiles/A/X",
      "access": [
        "read",
        "write"
      ]
    }
  ]
}

2.2. Champs de Données Communs (Common Data Fields)

Cette spécification définit un ensemble de champs de données communs conçus pour être utilisables dans différents types d'API. Cette spécification n'exige pas l'utilisation de ces champs communs par une définition d'API, mais les fournit plutôt comme composants génériques réutilisables que les concepteurs d'API peuvent utiliser. Les valeurs autorisées de tous les champs sont déterminées par l'API protégée, telle que définie par une valeur de "type" particulière.

locations: Un tableau de chaînes représentant l'emplacement de la ressource ou du RS. Ces chaînes sont généralement des URI identifiant l'emplacement du RS. Ce champ peut permettre à un client de spécifier un RS particulier, comme discuté dans la Section 12.

actions: Un tableau de chaînes représentant les types d'actions à effectuer sur la ressource.

datatypes: Un tableau de chaînes représentant les types de données demandées à la ressource.

identifier: Un identifiant de chaîne indiquant une ressource spécifique disponible à l'API.

privileges: Un tableau de chaînes représentant les types ou niveaux de privilège demandés à la ressource.

Lorsque différents champs de données communs sont utilisés en combinaison, les autorisations demandées par le client sont le produit de toutes les valeurs. L'objet représente une demande pour toutes les valeurs actions répertoriées dans l'objet à utiliser à tous les emplacements locations répertoriés dans l'objet pour toutes les valeurs datatypes répertoriées dans l'objet.

Dans l'exemple suivant, le client demande un accès en lecture et en écriture aux contacts et aux photos appartenant aux clients dans une API customer_information. Si cette demande est accordée, le client supposerait qu'il serait capable d'utiliser n'importe quelle combinaison de droits définis par l'API, tels que l'accès en lecture aux photos et l'accès en écriture aux contacts.

[
  {
    "type": "customer_information",
    "locations": [
      "https://example.com/customers"
    ],
    "actions": [
      "read",
      "write"
    ],
    "datatypes": [
      "contacts",
      "photos"
    ]
  }
]

Si le client souhaite avoir un contrôle plus fin sur son accès, il peut envoyer plusieurs objets. Dans cet exemple, le client demande un accès en lecture aux contacts et un accès en écriture aux photos dans le même point de terminaison d'API. Si cette demande est accordée, le client ne pourrait pas écrire sur les contacts.

[
  {
    "type": "customer_information",
    "locations": [
      "https://example.com/customers"
    ],
    "actions": [
      "read"
    ],
    "datatypes": [
      "contacts"
    ]
  },
  {
    "type": "customer_information",
    "locations": [
      "https://example.com/customers"
    ],
    "actions": [
      "write"
    ],
    "datatypes": [
      "photos"
    ]
  }
]

Une API PEUT définir ses propres extensions, sous réserve du type de l'objet d'autorisation respectif. Il est prévu que les concepteurs d'API utiliseront une combinaison de champs de données communs définis dans cette spécification ainsi que des champs spécifiques à l'API elle-même.